ENGAGE® Android SDK Authentication

Authenticating the host app with the ENGAGE platform is required to validate the communication between the device and platform. The Registration process validates up to three phone numbers and establishes the communication between the platform and device.

The following authentication mechanisms are possible:

• SMS: Requires user interaction to verify a PIN via SMS
• Silent Registration: Auto resolves in the background and does not require user interaction

Handlers

There are 3 main interfaces that the host app can implement that allows them to receive callbacks for certain actions involved in registration and number change.

EngageRegistrationHandler

interface EngageRegistrationHandler {
    /**
     * Called when challenge is initialized successfully
     * */
    fun onInitializationSuccess(userNumber: String?)

    /**
     * Called when number is registered successfully
     * */
    fun onRegistrationSuccess(userNumber: String)

    /**
     * Called when registration fails
     * @param phoneNumber Phone number that failed to register
     * @param error The reason of the error
     * */
    fun onRegistrationFailure(phoneNumber: String?, error: EngageRegistrationError)
}

EngageUnregistrationHandler

interface EngageUnregistrationHandler {
    /**
     * Called when number is unregistered successfully
     * */
    fun onUnregistrationSuccess(number: String)

    /**
     * Called when unregistration fails
     * @param error The reason of the error
     * */
    fun onUnregistrationFailure(number: String, error: EngageUnregistrationError)
}

EngageNumberChangeHandler

interface EngageNumberChangeHandler {
    /**
     * Called when number change results in success
     * */
    fun onNumberChangeSuccess()

    /**
     * Called when number change fails
     * @param error The reason of the error
     * */
    fun onNumberChangeFailure(error: EngageNumberChangeError)
}

Registration

To register a phone number, pass the phone number along with EngageResigistationHandler callback:

EngageApp.getInstance().register(number, engageRegistrationHandler)

Observation of the registration status is possible with these callback functions:

Initialization Success

InitializationSuccess is called when the registration is initialized successfully. For an SMS registration, this is the time an SMS message is sent to the given phone number:

EngageRegistrationHandler.onInitializationSuccess(number)

Registration Success

RegistrationSuccess is called when the registration is successfully completed for the given number:

EngageRegistrationHandler.onRegistrationSuccess(number)

Registration Failure

RegistrationFailure is called when the registration fails at any time. EngageRegistrationError depicts the cause of the error:

EngageRegistrationHandler.onRegistrationFailure(number, engageRegistrationErr or)

SMS Registration

For SMS registration, the 6-digit code delivered in the SMS needs to be passed to ENGAGE:

EngageSmsRegistration.completeWithCode(code)

Unregister

The unregister() function disassociates the given number. The number will no longer receive any ENGAGE content:

engageApp.unregister(number, engageUnregistrationHandler)

Change Number

The changeNumber alters the registered old number to a new number:

engageApp.changeNumber(oldNumber, newNumber, engageNumberChangeHandler)

Checking Registration

If the app has already been authenticated, the host app does not need to re-authenticate. A list of validated phone numbers may be generated by running the following check:

// For instances where numbers are not known
EngageApp.getRegisteredPhoneNumbers(context) // returns List<String> of phone numbers

// For instances where phone number is known
EngageApp.isPhoneNumberRegistered(context, number) // returns boolean

📘

Programming Tip:

To check if a phone number is registered, call:

Kotlin

val isEngageVerified = EngageApp.getRegisteredPhoneNumbers(context).isNotEmpty()