Integrating your application with Appdome DEV-Events™ and Nexmo Verify 2FA service

Nexmo Verify is a 2FA service, where the user submits a phone number, Nexmo sends an SMS or makes a voice call with the PIN code, and the user submits the PIN for verification.  Appdome is a mobile integration platform as a service (iPaaS) that allows users to add a wide variety of features, SDKs, and APIs to Android and iOS apps.

For more information about Nexmo Verify and how to use Appdome to integrate Nexmo Verify to your app, see: Add Nexmo Verify 2FA to your application.

This Knowledgebase article provides step by step instructions for integrating Appdome DEV-Events™ with Nexmo Verify service to any Android and iOS mobile app. With DEV-Events™ you can use Appdome to handle in apps events and complete Nexmo Verify authentication internally.

Prerequisites for adding Nexmo Verify to your application

In order to use Appdome’s no code implementation of Nexmo Verify, you will need:

• Appdome account
• Mobile App (.ipa for iOS, or .apk for Android)
• An account for Nexmo Verify service, and obtained from Nexmo dashboard:
  1. API key
  2. API secret
• Signing Credentials (e.g., signing certificates and provisioning profile)

Adding DEV-Events™ Code to Your App

DEV-Events™ events are coded in the application as the simplest method available to developers: in Android they implement Broadcasts and in iOS, they are push notifications. To let Appdome handle Nexmo Verify with DEV-Events™ events, follow this flow in the app’s code:

1. The application sends an event with ID NEXMOVERIFY_EVENT_VERIFY_PHONEINFO with key “phoneNumber” and value containing the phone number you want to verify
2. Appdome implementation of Nexmo Verify, after submitting this phone number will return an event NEXMOVERIFY_EVENT_VERIFY_PINCODE_NEEDED
3. An SMS message or a voice call with a PIN code should be on the way, once the user enters the PIN code value, the application should return it to Appdome with event ID NEXMOVERIFY_EVENT_VERIFY_PINCODE with key “pin” and value containing the PIN code is collected.
4. Appdome will verify the PIN code and return event NEXMOVERIFY_EVENT_VERIFY_PHONEINFO_DONE with key “status” that holds a value of “True” or “False”, indicating the success of validation.
5. In case of an error, Appdome will notify the application with event ID NEXMOVERIFY_EVENT_ERROR with key “error” and value containing the description of the error that occurred.

Assuming you have needed values in String objects:

Android

To send a DEV-Events™ event on Android, simply send a broadcast:

Bundle data = new Bundle();
data.putString(key, value);
Intent intent = new Intent(eventID);
intent.putExtras(data);
context.sendBroadcast(intent);

To receive an event on Android, simply create a BroadcastReciever and register it for events you need to receive:

BroadcastReceiver eventsReceiver = new BroadcastReceiver() {
    @Override
    public void onReceive(Context context, Intent intent) {
         Bundle extras = intent.getExtras();
         String event = intent.getAction();
         if(event.compareTo("NEXMOVERIFY_EVENT_ERROR") == 0) {
             if(extras != null && extras.containsKey("error")) {
                String errorText = extras.getString("error");
                //handle the error
            }   
         } else if(event.compareTo("NEXMOVERIFY_EVENT_VERIFY_PINCODE_NEEDED") == 0) {
            //get the PIN code and return it to appdome with DEV-Events event
         } else if(event.compareTo("NEXMOVERIFY_EVENT_VERIFY_PHONEINFO_DONE") == 0) {
            if(extras != null && extras.containsKey("success")) {
                String wasVerified = extras.getString("success"));
                //handle verification status
            } 
        }
    }
};
//Register the broadcast receive in onResume() and Unregister it in onPause ()
@Override
protected void onResume() {
      super.onResume();
      context.registerReceiver(eventsReceiver, new IntentFilter("NEXMOVERIFY_EVENT_ERROR"));
      context.registerReceiver(eventsReceiver, new IntentFilter("NEXMOVERIFY_EVENT_VERIFY_PINCODE_NEEDED"));
      context.registerReceiver(eventsReceiver, new IntentFilter("NEXMOVERIFY_EVENT_VERIFY_PHONEINFO_DONE"));
}

@Override
protected void onPause() {
      if(mReceiver != null) {
            unregisterReceiver(mReceiver);
      }
      super.onPause();
}

iOS

To send a DEV-Events™ event on iOS, simply post a notification with one of the event IDs and eventInfo dictionaries as explained above, and to receive events, create an observer, for example:

NSString *context = nil;

- (void)setUpListeners {
  // after Appdome sends the phone number to the Nexmo service, and kicks off the verification process,
  // it will notify the application that Nexmo verificaiton code is needed, and give the context which needs to be added to the reply,
  // see method "(void)sendPincode" below
    [[NSNotificationCenter defaultCenter] addObserverForName: @"NEXMOVERIFY_EVENT_VERIFY_PINCODE_NEEDED" object:nil queue:[NSOperationQueue mainQueue] usingBlock:^(NSNotification *note) {
        context = [[note userInfo] objectForKey:@"context"];
        // in PINCODE request from Appdome, we received the context we need to send back to verify the Nexmo verification code we will recieve via SMS or voice call
    }];
    // this notification will indicate verification process is done and notify us of success or failure of verification
    [[NSNotificationCenter defaultCenter] addObserverForName: @"NEXMOVERIFY_EVENT_VERIFY_PHONEINFO_DONE" object:nil queue:[NSOperationQueue mainQueue] usingBlock:^(NSNotification *note) {
        bool success = [[[note userInfo] objectForKey: @"success"] boolValue];
        // verification is done, "success" indicates success of verification operation
    }];
}
// this method will initiate the verification process. We send the phone number we want to verify
- (void)verifyPhoneNumber {
    if (self.phoneNumber.text) {
        NSMutableDictionary *userInfo = [[NSMutableDictionary alloc] init];
        [userInfo setObject: @"1234567890" forKey: @"phoneNumber"];
        [[NSNotificationCenter defaultCenter] postNotificationName: @"NEXMOVERIFY_EVENT_VERIFY_PHONEINFO" object:nil userInfo: userInfo];
    }
}
// user got the Nexmo verification code via SMS or voice call, app collected it from the user and wants to send it to Nexmo for verification
- (void)sendPincode {
    NSMutableDictionary *userInfo = [[NSMutableDictionary alloc] init];
    // send the code you recieved from Nexmo via SMS or voice call
    [userInfo setObject: @"1234" forKey: @"pin"];
    [userInfo setObject: context forKey: @"context"];
    [[NSNotificationCenter defaultCenter] postNotificationName: @"NEXMOVERIFY_EVENT_VERIFY_PINCODE" object:nil userInfo: userInfo];
}

Fusing your App with Nexmo Verify DEV-Events™ Support

1. Click the Fuse Tab. Note: a blue underline will appear showing the step is active
2. Click the Identity category
3. Toggle “ON” Identity Services
4. Select Nexmo Verify from the list
5. Enter the API Key you got from Nexmo Dashboard
6. Enter the API Secret you got from Nexmo Dashboard
7. Brand ID (optional): enter a string up to 18 characters which will be included in the verification SMS or voice call. If it is left blank, Appdome Nexmo implementation will use your application name, and the SMS show “<YourApplication> code: 1234. Valid for 5 minutes”.
8. API URL (optional): If you are using an alternative Nexmo server, enter here. Otherwise, leave blank. By default, Appdome’s Nexmo Verify implementation will use “https://api.nexmo.com“
9. Toggle “OFF” Dynamic UI™ to turn off Dynamic UI™ and turn on DEV-Events™
10. Click the Fuse My App button to complete Appdome’s Nexmo integration into the app.

Congratulations! Now you have a mobile app fully integrated with Nexmo Verify

After Adding Nexmo Verify to a Mobile App on Appdome

After you have added Nexmo Verify to any Mobile App on Appdome, there are a few additional steps needed to complete your mobile integration project.

Add Context™ to the Appdome-Fused App

Appdome is a full-featured mobile integration platform. Within Context™, Appdome users can brand the app, including adding a favicon to denote the new service added to the app.
For more information on the range of options available in Context™, please read this knowledge base article.

Sign the Nexmo Verify enabled Appdome Fused App (Required)

In order to deploy an Appdome Fused app, it must be signed. Signing iOS apps and Signing Android apps are easy using Appdome. Alternatively, you can use Private Signing, download your unsigned app and sign locally using your own signing methods.