Welcome to the Pngme v2.x Kotlin SDK!
This Readme will cover how the SDK works, get-started basics, and a sample Android app.
Contact Pngme for documentation on the legacy SDK (v1.0.34).
For the v2.x React Native docs and sample app, visit here.
For the v2.x Flutter docs app, visit here.
- The SDK accomplishes three tasks:
- register a mobile phone user with pngme's identity system
- request permission for SMS from the user, with a Permission Dialog Flow
- periodically send SMS data to pngme's data processing pipeline
- The SDK supports Android API level 16+
- The SDK exposes three methods: a main entrypoint method, and two helper methods
- Using the SDK requires an SDK
clientKey. Sign up and get started for free at the Pngme admin webconsole
When the SDK has been successfully integrated, financial data extracted from a user's SMS will be accessible in the Pngme admin Webconsole or via the Pngme REST APIs (see the API Reference docs).
To set up your project to use the Pngme SDK, follow these setup steps.
Resolve the JitPack package manager in your Gradle file.
Add the following to build.gradle.
allprojects {
repositories {
maven { url 'https://jitpack.io' }
}
}Add the SDK package to your Gradle file.
Add the following to build.gradle
dependencies {
implementation 'com.github.pngme:android-sdk:v2.0.4'
}Add your SDK clientKey to the project.
In the sample app, the clientKey is injected via the local.properties file.
For production applications, it is highly recommended that developers use a secure method for injecting the clientKey.
See here for some recommended methods:
How to secure secrets in Android.
Implement the PngmeSdk.go() method as needed in your app.
fun go(
activity: AppCompatActivity,
clientKey: String,
firstName: String,
lastName: String,
email: String,
phoneNumber: String,
externalId: String,
isKycVerified: Boolean,
companyName: String,
onComplete: Callback? = null
)| var name | description |
|---|---|
| activity | a reference to the current Activity |
| clientKey | the Pngme SDK key for your account |
| firstName | the mobile phone user's first name |
| lastName | the mobile phone user's last name |
| the mobile phone user's email address | |
| phoneNumber | the mobile phone user's phone number, example "23411234567" |
| externalId | a unique identifier provided by your app (if none available, pass an empty string "") |
| isKycVerified | a boolean, indicating if your app has verified the user's identity using KYC |
| companyName | your company's name; this is used in the display header of the Permission Dialog Flow |
| onComplete | a callback function that is called when the go method has completed |
The go method is the main entrypoint method for invoking the PngmeSdk.
The go method is idempotent, and can be invoked multiple times.
The go method performs three tasks.
- register a
userin Pngme's system using an Android Onetime Worker - show a Permission Dialog Flow in the current Activity to request SMS permissions from the user --
this runs the first time, and only the first time, that
gois invoked - check for new SMS messages and send them to Pngme's system every 30 minutes using an Android Periodic Worker
The go method should be invoked and left to complete while the activity is in a running state.
The onComplete callback is a useful callback, for example,
in determining when it is safe to change the Activity state.
Additionally, the onComplete callback is a useful callback in determining
when the activity is no longer in use by the Permission Dialog Flow.
The onComplete callback will be invoked when three conditions are satisfied:
- the Onetime Worker for registering a user with Pngme's system has been instantiated
- the Period Worker for periodically sending SMS data to Pngme's system has been instantiated
- the Permission Dialog Flow has exited
fun resetPermissionFlow(context: Context)| var name | description |
|---|---|
| context | the current app Context |
As noted above, the Permission Dialog Flow will only run the first time that the go method is invoked.
If your app needs to implement logic to show the Dialog Flow again,
then you can reset the permission flow by calling resetPermissionFlow.
The next time you call go, the Permission Dialog Flow will show again.
Example:
PngmeSdk.go(args) // permissions flow runs
PngmeSdk.go(args) // permission flow will NOT show again
PngmeSdk.resetPermissionFlow(args)
PngmeSdk.go(args) // permission flow runsSee the [code snippets](#Show Permissions Flow Multiple Times) in the below documentation on the example app for implementations where you might consider using this method to control the Permission Dialog Flow.
fun isPermissionGranted(context: Context): Boolean| var name | description |
|---|---|
| context | the current app Context |
A simple helper function to indicate if the user has accepted the SMS permissions request.
Returns true if the user has accepted the SMS permission request.
Returns false if the user has denied the SMS permission request.
This repository is a sample Android app, which uses the Pngme SDK.
This app uses the local.properties file to inject the SDK clientKey.
Please note that this is for example purposes only.
As noted in [Step 3](#Step 3) of the get [started section](#get started),
it is highly recommended that a production application use a more secure method of injecting the clientKey secret.
This app can be compiled and emulated locally, with or without a valid SDK clientKey.
If a valid SDK clientKey is used, then data can be sent thru to the Pngme system.
Add the following to your local.properties file:
SHARED_PREF_NAME=my_app_shared_pref
CLIENT_KEY=<my_app_clientkey>
Replace <my_app_clientkey> with a your SDK client key.
As noted, the app can build and be emulated without a valid SDK key.
However, a valid SDK key is necessary to send sample data to the Pngme system.
The sample app demonstrates a simple flow:
- user creates an account with the app
- the user goes to apply for a loan, and has the option of selecting to use the Pngme service
- if the Pngme service is selected, the SDK is invoked, and the Permission Flow is presented
- when the permission flow exits, the user is presented with the loan application page
The SDK is implemented in the PermissionFragment, when the user clicks on the Continue button:
continueButton.setOnClickListener {
// save state of checkBox
if (usePngmeCheckBox.isChecked) {
setPngmeAsChecked()
val mainActivity = (activity as MainActivity)
getUser()?.let { user ->
PngmeSdk.go(
mainActivity,
BuildConfig.CLIENT_KEY,
user.firstName,
user.lastName,
user.email,
user.phoneNumber,
"",
false,
MainActivity.COMPANY_NAME
) {
navigateToLoadApplication()
}
}
} else {
navigateToLoadApplication()
}
}The app remembers the selection in step 2. If the user chooses to enable the Pngme service, then the checkbox stays selected for all future loan applications. The Permission Flow is only showed the very first time, regardless of if the user accepts or denies the permissions.
Alternative behavior is to continue requesting SMS permissions if they were previously denied. Adding the following snippet will reset the Permission Flow if SMS permissions had been previously denied but not permanently ignored.
continueButton.setOnClickListener {
// save state of checkBox
if (usePngmeCheckBox.isChecked) {
setPngmeAsChecked()
if (!smsPermissionGranted() && smsNeverPermanentlyIgnored()) {
context?.let {
PngmeSdk.resetPermissionFlow(it)
}
}
val mainActivity = (activity as MainActivity)
getUser()?.let { user ->
PngmeSdk.go(
mainActivity,
BuildConfig.CLIENT_KEY,
user.firstName,
user.lastName,
user.email,
user.phoneNumber,
"",
false,
MainActivity.COMPANY_NAME
) {
navigateToLoadApplication()
}
}
} else {
navigateToLoadApplication()
}
}As noted above, the primary responsibility of the Pngme SDK is to send SMS data to the Pngme system. This can be tested in a sample app running in the local emulator, assuming the emulated app is running with a valid SDK token.
The following text message is of a recognized format for the Stanbic bank sender: Stanbic.
Acc:XXXXXX1111
CR:NGN4,000.00
Desc:HELLO WORLD! SAMPLE MESSAGE
Bal:NGN50,000.00
You can inject this fake SMS into the emulated phone by following these steps. It is advisable that you pre-populate the emulated phone with the SMS before running the sample app.
- Open the
morewindow in the emulator settings - Navigate to the
phonesection - Set the sender to the string
Stanbic - Copy/Paste the above same message into the message box
- Hit
Send Message
After following the above steps to send a fake SMS, run the sample app. The fake SMS will be sent to the Pngme system using the SDK token from your Pngme account. If the sample app runs successfully, the financial data in the text message will be accessible via the Pngme REST APIs or in the Pngme webconsole.
So you have a working app! Congrats! But... it's not over yet.
You will still need to whitelist your app with the Google Play store.
This is a special step necessary for any apps that require SMS permissions from the user.
The whitelisting process is not hard, but if you have never whitelisted an app before, you may want assistance.
Pngme can offer support in whitelisting your app, free of charge.
Simply contact us
and also visit our guide: Going Live.
We'll help you get your app through the approval process faster than you can say Hello World!
If you insist on whitelisting your app without Pngme's assistance, please let us know and we will provide you with instructions. These will help you avoid setbacks when submitting your app for review.