Native Android Integration Guide

Installation

Add the JitPack repository to your build file

Add the following code to your Android build.gradle under repositories.

    allprojects {
        repositories {
            ...
            maven { url 'https://jitpack.io' } // <-- add this line
        }
    }

Stable version: Jitpack 1.0.34

Add dependencies

Next you must add the following dependency in your app level build.gradle

    dependencies {
        implementation 'com.github.pngme:android-sdk:vX.Y.Z'
    }

❗️

Android API Support

The minimum Android API version minSdkVersion is API 16 (Android 4.1)

Grant Read SMS Permissions

The SDK will ask the user to grant access to their SMS logs through the Android Native permissions dialogue at SDK runtime.

Manifest.permission.READ_SMS

🚧

Do Not Add Permissions to Manifest

There is no need to add the Read_SMS permission to your applications manifest. The SDK will add it automatically in addition the INTERNET permission.

Set Your Environment & ClientKey

Before starting the SDK you must setup the environment.

setEnvironment(
    environment: Environment, 
    clientKey: String, 
    context: Context
)
  • environment: Pngme SDK exposes an Environment class so you can use our Environment.Sandbox to test the app and then you must move to Environment.Prod once the app is ready to be launched to real users.
  • clientKey: Each environment works with a unique clientKey. Both keys can be requested by the account manager.
  • context: Android context reference.

❗️

Set Environment Parameters

All of the parameters in the Environment class are required

Setup the permission flow and SDK open actions

Implement the following steps:

❗️

Warning

It is important that developers follow the order of the functions outlined below

Step 1: Initialize the SDK

Call the init function in the Activity constructor. This allows the SDK to register the permissions listener to capture user interactions.

PngmeSdk.init(this) // 'this' is AppCompatActivity

Step 2: Register a user under your company (client) in the SDK

Provide user and company (client) information:

PngmeSdk.registerUser(user) // 'user' is UserInfo

The SDK exposes a UserInfo object to register a user's information.

data class UserInfo (
    companyName: String // <-- Your company (client) name will be shown to users
    userFirstName: String
    userLastName: String
    userPhone: String
    userEmail: String
    externalId: String?  // <-- Optional Field

    // You can pass your users `uuid` in this field
    // this can be useful to identify your users later
    // when obtaining processed data from our servers
)

Step 3: Start the SDK in your user journey

A developer can start the PngmeSdk by calling the PngmeSdk.start function. When this function it called it will launch the SDK and prompt the end user to grant READ_SMS permissions from the SDK flow.

PngmeSdk.start(onComplete, onError, onCloseDialog) 

🚧

Important

If the start method is called when the user has already granted permission to READ_SMS and has accepted the terms and conditions of the SDK, the permission flow will not restart, and there is no further action needed from user (as the user has already granted permission).

UserInfo Definitions

Callback nameParamDescription
onCompleteNo ParamThis callback was DEPRECATED
onError(errorMessage: String)

It will return an error message if something goes wrong

Ex: Connection errors, BE errors.

onCloseDialogNo paramIt will be called when a user dismisses the permission dialog

Did this page help you?