Search…
Native Android SDK Installation Guide
Pngme's Data SDK fetches user-authenticated data from Android devices using Kotlin (Android native language).

Installation

Add the JitPack repository to your build file.
Add the following code to your Android build.gradle under repositories.
1
allprojects {
2
repositories {
3
...
4
maven { url 'https://jitpack.io' } // <-- add this line
5
}
6
}
Copied!
Stable version:
Add the following dependency in your app level build.gradle
1
dependencies {
2
implementation 'com.github.pngme:android-sdk:vX.Y.Z'
3
}
Copied!
The minSdkVersion supported is API 16 (Android 4.1)

Permissions

The SDK asks the user for the following permissions at runtime:
1
Manifest.permission.READ_SMS
Copied!
There is no need to add the above permission in your app Manifest. The SDK will add it automatically, as well as the INTERNET permission.

Environment & ClientKey

Before starting the SDK, we need to set up the environment.
1
setEnvironment(
2
environment: Environment,
3
clientKey: String,
4
context: Context
5
)
Copied!
  • 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.
All the fields are required

Setup and Opening permission Flow

Start the SDK with the following steps:
  1. 1.
    Call the init function in the Activity constructor. This allows the SDK to register the permissions listener to capture users interactions.
1
PngmeSdk.init(this) // 'this' is AppCompatActivity
Copied!
2. Provide user and company information:
1
PngmeSdk.registerUser(user) // 'user' is UserInfo
Copied!
The SDK exposes a UserInfo object to register a user's information.
1
data class UserInfo (
2
companyName: String // <-- Your company name will be shown to users
3
userFirstName: String
4
userLastName: String
5
userPhone: String
6
userEmail: String
7
externalId: String? // <-- Optional Field,
8
// You can pass your uuid in this field,
9
// this can be useful to identify your users latter
10
// when obtaining processed data from our servers.
11
)
Copied!
4. Start PngmeSdk, after calling this function SDK will popup permission flow. If start method is called when permission are approved and user already accepted terms and condition, it will not open the popup since there is no action needed from user.
1
PngmeSdk.start(onComplete, onError, onCloseDialog)
Copied!
Callback name
Param
Description
onComplete
No Param
This callback was DEPRECATED
onError
(errorMessage: String)
It will return error message if something goes wrong
Ex: Connection errors, BE errors.
onCloseDialog
No param
It will be called when a user dismisses the permission dialog
Its important to follow the order of this functions

Sending Extra data to Pngme

Once permissions were approved and PngmeSdk is sending SMS you can send extra data regarding user information and user's loan.

Send KYC Data

If you are checking user identity in your app, you can send this data to Pngme in order to be able to see it when using our Web Admin.
Note: Currently our API is not processing: id Number, idType, idImage and issuer Data. We will continue providing this solution in the near term. We recommend sending the data so in near future when the API includes these fields you do not have to release a new version.
In case that you KYC consists on more that one id document verification, you can send different documents by calling sendKYCData multiple times.
Remember that this method should be called after Start method
1
data class KYCDataInfo (
2
var kycVerified: Boolean <-- Required
3
var idNumber: String?
4
var idType: String?
5
var idImage: String?
6
var issuer: String?
7
)
Copied!

KYC Params

Param
Required
Type
Description
kycVerified
Yes
Boolean
Required boolean param, here you should pass true if the user successfully passed your KYC process.
idNumber
No
String
On this property you should pass the idNumber ej : 'G0000000'
idType
No
String
On this param you should pass the document type ej: 'passport', 'nationalId
issuer
No
String
Issuer or organization that checks user identity
idImage
No
String (Url Or Base45 encoding)
Used to send user document picture
Example:
1
import com.pngme.sdk.library.PngmeSdk
2
import com.pngme.sdk.library.data.KYCDataInfo
3
// end of imports
4
5
val kycDataInfo = KYCDataInfo()
6
kycDataInfo.kycVerified = true
7
kycDataInfo.idImage = "https://yourimage.com"
8
kycDataInfo.idNumber = "idNumber"
9
kycDataInfo.idType = "DriverLicence"
10
kycDataInfo.issuer = "Government"
11
PngmeSdk.sendKYCData(kycDataInfo, context)
Copied!

Send Loan info

The library allows you to send Loan information to Pngme server, to be consumed later from api or Web Admin.
To send a loan timestamp and id via our SDK we expose a LoanInfo object to register a user's loan application event, such as the id and the timestamp specified in milliseconds.
1
data class LoanInfo(
2
var idLoan: String
3
var timestamp: Long
4
)
Copied!

Loan Params

Param
Required
Type
Description
idLoan
Yes
String
On this property you should pass the LoanId
timestamp
No
Long
Optional loan applied timestamp
Example:
1
import com.pngme.sdk.library.PngmeSdk
2
import com.pngme.sdk.library.data.LoanInfo
3
// end of imports
4
5
val loanInfo = LoanInfo()
6
loanInfo.idLoan = "YourLoanUuid"
7
loanInfo.timestamp = 1634136418687
8
PngmeSdk.sendLoanInfo(loanInfo, context)
Copied!

Updating user information

Once you started the SDK our servers will create a user with all the params that you sent to registerUser()method. But it's possible that for any reason some of the user's data was changed on your app and you want to notify the change to Pngme in order to keep the records updated and consistent.
In order to be able to update user information we expose a method where you can pass updated data. It's important to know that the method needs to receive all user information again:
1
updateUser(userInfo: UserInfo, context: Context): Boolean
Copied!
This method returns a true if the user information was successfully updated in our server.
You must complete the userInfo object with all the information, not just the fields to be updated.
You can modify any of the userInfoattributes except foruserPhone, that must be the same it was when registerUser() was called.
Since it's used for identifiying the users in our server, if we receive any other value a new user will be created instead of updating the current one.

Auxiliary methods

Auxiliary methods allow you to get the status of user permissions during a session.

Checking permissions

Check a permission status by invoking hasPermission function. This will return a boolean:
1
import com.pngme.sdk.library.PngmeSdk
2
// end of imports
3
4
PngmeSdk.hasPermission(context)
Copied!

Checking if the session started

There are a couple of exceptions where permissions were accepted, but SMS messages are not being sent yet.
Exception reasons:
  • The user granted permission via Android app settings (but never seen Permission flow in order to accept terms and conditions)
  • The SMS SDK was opened, the user accepted permissions but for whatever reason (network issue, no connection, timeout) and Pngme's API did not start a new session.
To start sending the SMS messages, open permission flow by calling start method again. Once a session starts, the SDK will start sending SMS data on the background. To know if a session was started, expose the boolean operation: needInitOfSDK and can be use on that way:
1
import com.pngme.sdk.library.PngmeSdk
2
// end of imports
3
4
PngmeSdk.needInitOfSDK(context)
Copied!

Force Send SMS (Recommended)

Once you follow previous section, and user accepted SMS permission the library will continue sending SMS every 12 hours on background (even with app closed) by using native android worker managers. For certain devices, configurations or android customization layers this worker managers could be stoped. Ex: devices the OS put the unused apps to sleep, in order to save energy. To avoid this situation we expose forceSentSMS method. We highly recommend to call this method as soon your app opens, so every time that you app is opened you ensure to send all SMS that were not be sent previously.
forceSentSMS runs on background and it's invisible for users. if you call forceSentSMS before asking for permission there is no problem it will ignore the action and will start sending sms after user accepts permisions.

How to use it:

1
PngmeSdk.forceSentSMS(context)
Copied!
We highly recommend to call this method in your app start to be sure that it's called every time that app is opened .

What's new

1.0.33 release on November 8 of 2021

  • Add custom prefix for all the sdk resources

1.0.32 release on October 21 of 2021

  • Fix bugs & improvements

1.0.31 release on October 20 of 2021

  • Add support up to Android API Level 16

1.0.30 release on October 11 of 2021

This release includes:
  • UpdateUser method
  • Better handing of client keys (now there are 1 key for prod and other for testing)
  • Recovery mechanism driven by servers in order to get all sms in case of data lost

1.0.29 release on July 29 of 2021

This release includes better analytical bug tracking. Implementation changes: this version requires Kotlin 1.4.32 or newer to run (instruction at the top of this doc).

Support

We offer full developer support for installing the Android Native Data SDK including the following channels:
  • Slack
  • WhatsApp
  • Telegram
  • Zoom
Last modified 23d ago