Skip to content

App Registration for Mobile SDK 3.x

Jump to bottom
adamrangs edited this page Aug 8, 2022 · 2 revisions

App Registration for Mobile SDK 3.x

For SDK v3.0.0 onwards, you are required to register your Apps on the developer portal to obtain the correct clientId and clientSecret with the required scopes by following this guide.

  1. Visit https://developer.webex.com/my-apps/new/integration

  2. Choose Yes for Will this integration use a mobile SDK?

  1. Provide a name for your integration. This will be shown on the permissions consent page for your users
  1. Provide a contact email for your App.
  1. Upload an icon or choose from one of the defaults that is available.
  1. Provide a description for your app. This will also be visible to your users on the consent page.
  1. Provide one or more redirect URIs for your app. These will be used by the OAuth2 flow to capture the auth code. You'll be providing this to the SDK while creating the OAuthAuthenticator instance.
  1. Now click on Add integration at the bottom. Congrats, now your integration has been created successfully.

Note: If you do not plan on using CUCM incoming call push notification capabilities, Please feel free to skip the remainder of the guide.

Push notification for iOS App

Follow the steps below for enabling CUCM push notifications

  1. To create an APNs auth key, Visit the Apple Developer Member Center.

  2. Click on “Certificates, Identifiers & Profiles”.

  3. Go to Keys from the Left Menu and Create a new Auth Key by clicking on the “+” button.

  4. On the following page, add a Key Name, select APNs and hit Continue

  5. Hit the register button.

  6. On this page, you will be able to download your auth key file

  7. In the webex developer portal, navigate to the settings page of your integration and click on Add new APNS. Here you'll have to base64 encode your APNS private key and fill in the other fields in the JSON format as below. e.g:

    {
    "keyId": "73Q8JZND1V",
    "bundleId": "com.example.KitchenSink",
    "teamId": "D7A3215KHV",
    "keyFile": "LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0tCk1JR1RBZ0VBTUNNR0J5cUdTTTQ5QWdFR0NDcUdTTTQ5QXdFSEJIa3dkd0lCQVFRZzRWM0dJOVZ1SWFjWXNTcksKSU5qYzBNQ3RJVkcyMmFlSVNtL2tFQjBia2phZ0NnWUlLb1pJemowREFRZWhSQU5DQUFTZWdZT0RNTzhuNTZDQgpnQUxLek1yUkEybE1UMnZJallQQ1Y3dTN1UVE2N2FZenFCN0JYdW16Y2NPRFlSYVhBeUdUcjg1L0c3R2htdkJOCkIyUnhQTkQ2Ci0tLS0tRU5EIFBSSVZBVEUgS0VZLS0tLS0="
}

    Note: Every time you add new APNS credentials, the previous one is overridden. Click on clear to clear all stored credentials

    Note: It may take up to 24 Hours for your unique app id to become active for push notifications as the server maintains a cache of applications, and syncs them every 24 hours

  8. In your app, please fetch your APNs VOIP token by using PKPushRegistryDelegates func pushRegistry(_ registry: PKPushRegistry, didUpdate credentials: PKPushCredentials, for type: PKPushType) method.

  9. Create the following payload and make a PUT request to

    https://<cucm_ip>:8443/cucm-uds/user/<userid>/device/<devicePkid>/devicetoken

    <token>
    <pushNotifyToken>pushNotifyToken</pushNotifyToken> <!-- Your APNs voip device token -->
    <pushChannelType>APNS</pushChannelType><!--format : APNS, APNS:dev-->
    <key>base64_encoded_secret_key</key><!--Base64 encoded secret key. This secret key will be used for encryption of notification payload by CUCM. Same secret key(base64 decoded) should be used for decrypting the APNS payload-->
    <algorithm>A256GCM</algorithm>
    <application>you_unique_app_id_from_dev_portal</application>
    <payloadVersion>V2</payloadVersion>
</token>

    NOTE: For cucm_ip and devicePkid values in the above request, communicate with your CUCM admin.

    Check SSO Access Token with UDS for SSO based authentication with UDS

    Check UDS API References for more details.

  10. When you receive a new push notification from CUCM, you can listen for it in func pushRegistry(_ registry: PKPushRegistry, didReceiveIncomingPushWith payload: PKPushPayload, for type: PKPushType, completion: @escaping () -> Void) method. The payload will be encrypted using the above key that you've provided. You'll need to decrypt it using the same key and algorithm. A reference third-party pod for this decryption would be SwCrypt.

  11. Your implementation of the didReceiveIncomingPushWith method must report notifications of type VoIP to the CallKit framework, by calling the reportNewIncomingCall(with:update:completion:) method of your app's CXProvider object. When you call that method, the system displays the standard incoming call interface to the user unless an error occurs. Check Apple's documentation for further details

  12. After decrypting the push notification, you'll have a field called pushId. You'll need to pass this to webex.phone.getCallIdFromNotificationId(notificationId: pushId, notificationType: .CUCM) and you'll get a callId which can be used to answer the call

Push notification for Android App

Follow the steps below for enabling CUCM push notifications for the android application

  1. Get your FCM service account file. Go to Firebase Projects page

  2. Select your project and as shown below and go to your Project Settings

  3. Click on the Service accounts tab, then click Generate new private key. A file named <your-project>-firebase-adminsdk-<first-numbers-of your-key>.json will be generated. This is your ServiceAccount json file

  4. On the webex developer portal, go to your integration's settings page and Click on Add new FCMs. Here you'll have to base64 encode your FCM serviceAccount json file's content and fill it in as the value for the serviceAccount key in the json, as shown below. e.g:

    {
    "serviceAccount": "ICAgewogICJ0eXBlIjogInNlcnZpY2VfYWNjb3VudCIsCiAgInByb2plY3RfaWQiOiAia2l0Y2hlbnNpbmstZGVtby1hcHAtYXY2YWIiLAogICJwcml2YXRlX2tleV9pZCI6ICI3N2Q5YTE2YjExMjZlOGJkY2VhY2tjNDk0ZGQwMzVlYzQwZTk2OTVjIiwKICAicHJpdmF0ZV9rZXkiOiAiLS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0tXG5NSUlFdlFJQkFEQU5CZ2txaGtpRzl3MEJBUUVGQUFTQ0JLY3dnZ1NqQWdFQUFvSUJBUURWcnhrd1RGQXlKaDl6XG5TTENXdHVLNzkwTVk2ZVpPSWE3SUZUclFjUlpWeG9QeVJpOXEyOGJhRTFWeUZ5MC9tZVV4eGNKYU9vUDZ3a1AxXG5uU0NBRTJhbk5NRUNBdWoyWWRkeG1RSDBJdGQrdWptbHUrdmdQdW5JamFwUys0ajFoVDlKcG54M1phSjVJZXpSXG5Xa0lLWXFEZUVrY1hpSlZNYVE1aEZnRFh5RnV3L3lYakJFY0dPTzdpV0JmRE1xR041N1cybWZkWXZrZVg2ZXBOXG5KeWtYSDRvSlhYYVNzMldjbFBuNExYNFRqekFJelRvZE1NaUF2YzJhekE2dkxOQmZYZUdwSWtOajlzdWpWWGN1XG5lT3VWMzM4U2hEQXhydTNuUkNCV3U2Y2s0S3l1SGw3eUZ1NHBQQU96ZDlFS3pCa3UyVXFnT0g5eUwySkVYT0xMXG5aNGxZNXh3bEFnTUJBQUVDZ2dFQUdiTFIvdkRDbVZGajZXZTEweDVpRk5TSEpZVWx6VUk0UkxobTV5QWVuVWkvXG5ZQ0VJUFZ2NnBZbjdOZm9yRnpIUk1tUHovSWw2aTJzWEpNQVZvMG1TQ0N4c1JPdG9MSTkyUzJOcExIMFBPUjY0XG41YUY4Mis1OUM4RmIyVmlHYjI2cnZwWU85SVlNM1BBVFROZER4MzkybE5hU1piWm5yRFdiUk5wU1ZpRXl3ODJuXG5hTHRPQXYxcWpHeUJjUzV4dzNlVlNUS096TjZwbGVpVWZaVlRIRmFQYStrRnNVMnpOYVg4S1g5RnFLUWorUW9BXG5EdVhzTFBYR1ZZWVd3MXAwblNaaXBDOEREeFI0NitTK21QQmNHUU41TXI5UW5FK0doNVBJclIwTHlCbGVQT3BDXG5Oa1VFZXNpQVBZZ2NDZExsT1dRMXIwUXB5bjI1L1YvZm1LWmtSeGl4bVFLQmdRRHowbTlRSjNheGtSeGxKRnNUXG5yTDVkYkM2ZFZ1VURPemMzQjBvNGkvakJ2OWlxd0t5T0RwdFFPSjgrYVBId0pvVVlVUThZY0kzK0gzNDMzblVoXG56NVBTbUVTTnozci9ZMUdKVWJTMTgvZTU3blF4UnZCMVVURnVlQjE1aXVzTUpkbmJEL0puQUJpUmZ1dEtHL0F3XG52WGV5TURGOW9mRU50RnRDTVAvckw0bTh1UUtCZ1FEZ1cwL0lMYlpMTVFjRTlhWVVxSmdpWjd6YU0wMEUrWkpRXG5Fc2sxdEdNMkZreW91emlYelJQbnNEb3BLUnM4YzVEc3hORHFYRmFFWnYrVjB4TEYvQW1RY0tNQ2g4NmxlemFLXG5vMGxEVmNVS3Z5VjZWRUppMGp0eTk1UnB4QjBnejdVdEp3aWNnYkFkM0l5S2dnMkhJN0w0ekhoOW5VeEJ2SzNXXG5lSHJNdHN6Y3pRS0JnUUNyOHJuQm96TVhvcWlOdzRmZlpqR1NITnI2NXU3MnltbjBDdFlTN3ROdGYraEM4MEk5XG5wSnR2aFo3NEduYVV6L1dJNHBGc3dPUENWVjlqOHlSVHhkb1A2SVpnSS9RdjYxRHpNSVhxMDdUZWtRV3NRc1VOXG5WMGN2Q3RKdWhzT2dlNGtaN2pNYTVIeHZEenpMdE13ODgwRllqcGc0YTE1ZU5kVXQ1dlIwWGNBYk1RS0JnRGdHXG4xWCtaMnNJZ05pNkk0YmFhKzVMcjhQOVVmRkZYdWJBQllQbm1XRGd6aldVOWk3NXMyaUdyb25xUTUxcExTYysyXG52cTBuN2ZzV2RaRUdxdE9DUXlrczE2aFVIY2k1WWo5dzAyVGJVRitFcUdsS0RXSDhPaGhWdDF4S096UHNhc1FoXG4wVWEwSkRUdzFLL3FGbEsvR1h5RUl6ckxRelhQVm1JT3FDdmpJbm1wQW9HQVVKN0ttSmNQRzNsc01aL0tUTDk2XG5uZjRSQXRLRXJCTnNWY2dkMFNVZ0F1WlI4NlhDaVhGQzYzdVE1NEViaXBiem1sQ3dGL2IyeFJGZTZ4RzlBZ0lFXG5kVjkvdXlLVG95Qk5zdXNwdm9jdEEyMHNUdUR1M1dOQWd5S0tRVTlaVVdnbDZHWFVKM0t5QWdQL0xGTStnU2RoXG41K1RHaTJ0RWVZa0w5aUg2cUd2NzJqRT1cbi0tLS0tRU5EIFBSSVZBVEUgS0VZLS0tLS1cbiIsCiAgImNsaWVudF9lbWFpbCI6ICJmaXJlYmFzZS1hZG1pbnNkay1pMmthZEBraXRjaGVuc2luay1kZW1vLWF2NmFiLmlhbS5nc2VydmljZWFjY291bnQuY29tIiwKICAiY2xpZW50X2lkIjogIjExMDQ3MjQ0Nzc2NDEwNDMwMDM2MSIsCiAgImF1dGhfdXJpIjogImh0dHBzOi8vYWNjb3VudHMuZ29vZ2xlLmNvbS9vL29hdXRoMi9hdXRoIiwKICAidG9rZW5fdXJpIjogImh0dHBzOi8vb2F1dGgyLmdvb2dsZWFwaXMuY29tL3Rva2VuIiwKICAiYXV0aF9wcm92aWRlcl94NTA5X2NlcnRfdXJsIjogImh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL29hdXRoMi92MS9jZXJ0cyIsCiAgImNsaWVudF94NTA5X2NlcnRfdXJsIjogImh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL3JvYm90L3YxL21ldGFkYXRhL3g1MDkvZmlyZWJhc2UtYWRtaW5zZGstaTJrYWQlNDBraXRjaGVuc2luay1kZW1vLWF2NmFiLmlhbS5nc2VydmljZWFjY291bnQuY29tIgp9"
}

    Note: Every time you add a new FCM secret, the previous one is overridden. Click on clear to clear all stored secrets

    Note: It may take up to 24 Hours for your unique app id to become active for push notifications as the server maintains a cache of applications, and syncs them every 24 hours

  5. In your android app, fetch your FCM registration token. Check FCM Documentation for android for how to get your registration token

  6. Create the following payload and make a PUT request to https://<cucm_ip>:8443/cucm-uds/user/<userid>/device/<devicePkid>/devicetoken

    <token>
    <pushNotifyToken>pushNotifyToken</pushNotifyToken> <!-- Your FCM device/registration token -->
    <pushChannelType>FCM</pushChannelType>
    <key>base_64_encoded_secret_key</key><!--Base64 encoded secret key. This secret key will be used for encryption of notification payload by CUCM. Same secret key(base64 decoded) should be used for decrypting the FCM payload-->
    <algorithm>A256GCM</algorithm>
    <application>you_unique_app_id_from_dev_portal</application>
    <payloadVersion>V2</payloadVersion>
</token>

    Now your app is ready to receive FCM notification for incoming CUCM calls.

    NOTE: For cucm_ip and devicePkid values in the above request, communicate with your CUCM admin.

    Check SSO Access Token with UDS for SSO based authentication with UDS

    Check UDS API References for more details.

  7. FCM notification would contain data in the following format:

    class PushRestPayloadModel (
@SerializedName("type") val type: String?,
@SerializedName("pushid") val pushId: String?,
@SerializedName("displayname") val displayname: String?,
@SerializedName("displaynumber") val displaynumber: String?,
@SerializedName("payloadversion") val payloadversion: String?,
@SerializedName("huntpilotdn") val huntpilotdn: String?,
@SerializedName("ringexpiretime") val ringexpiretime: String?
)

    This payload data will be in an encrypted format and needs to be first decrypted using the same key that was provided in step 6 above.

    NOTE: Need to use some third-party library for encryption/decryption which supports the AES256GCM algorithm.

    An example library that you can use is given below :

    Gradle dependency -

    implementation “com.nimbusds:nimbus-jose-jwt:9.0”

    Sample method for decryption using the nimbus jose library:

    @param payload : the payload obtained from FCM notification
@param decryptionKey : the key that was used for encryption. // Decode if encoded in base64
fun decryptPushRESTPayload(payload: String, decryptionKey: String): String {
    val jweObject = JWEObject.parse(payload) jweObject.decrypt(DirectDecrypter(decryptionKey.toByteArray()))
    val decryptedPayload = jweObject.payload
    return decryptedPayload.toString() 
}

  8. After decryption, you'll have a field called pushid, as shown in the class PushRestPayloadModel in step 7. You'll need to pass this to webex.getCallIdByNotificationId(notificationId = pushId, callType = NotificationCallType.Cucm) and you'll get a callId which can be used to answer the call

Clone this wiki locally