Cm Hybrid message plugin

This plugin is a Cordova wrapper for the Hybrid Message SDK from CM Telecom.

(https://github.com/CMTelecom/cm-plugin-hybridmessaging)

Referencing version: #1.0.0

 When using this plugin in a mobile application, it will be possible to send messages to the mobile users using push notifications or SMS depending on which channel is available at the moment as well as letting the users retrieve messages sent to them in the past using a convenient mailbox-like API.

If the user is using your application, it firstly requires a one time verification with his phone number. This will register his device and his phonenumber in CM.
 The user will be ready to receive SMS as a pushnotification.

 This document will show you:

1. How to configure
2. How to use it
3. An example implementation flow

In order to make the plugin work in Outsystems, serveral actions are required:

Configure Firebase

The only thing required is creating a firebase project. There’s no other plugin required to make push notifications work. (ex. Pushwoosh is not required, the Cordova plugin does all the work)

• https://console.firebase.google.com/
• Create Project
• Obtaining the following required information:
• Server API Key (use legacy server key)
• SenderID
• Plugin is ready to use

Configure APNS

Follow the tutorial on https://firebase.google.com/docs/cloud-messaging/ios/certs to generate the app ID, app provisioning profiles and an APNs SSL certificate

IMPORTANT: the APNs SSL certificate needs to be generated for the "production" environment (however note that it can still be used in combination with the APNs development sandbox)

Be sure to upload the newly generated push-enabled provisioning profile to OutSystems when preparing the builds for hybrid-messaging-capable apps.

Configure Hybrid Messaging Plugin

Login into the CM Portal

https://login.cmtelecom.com/

And create a new application in the App Manager:

https://appmanager.cmtelecom.com

Fill in the required information:

• Name
• Type : Default Messaging
• Sender Name (for example Providit)
• Registration callback url : leave empty
• Server API Key: the Legacy Server key from your firebase project
• SenderID : The sender ID from your firebase Project
• Leave the rest empty and save

For IOS : Don’t forget to upload your p12 certificate at the CM CP.

Using the Outsystems cordova wrapper

Available methods wrapped in a client action:

ConfigureService client action

Input parameters required: API key, API secret, SenderID

ConfigureCM:

Configures the hybrid messaging service with API key, API secret(generated from CM portal), Android sender ID and relevant callbacks

**IMPORTANT**: the ConfigureService method should be called as early in the application's life cycle as possible and prior to executing any other call related to hybrid messaging. All hybrid messaging methods called prior to service configuration will return with an error.

StartMessagingService

Enables the hybrid messaging service

**IMPORTANT**: the StartMessagingService method should be called after executing the ConfigureService method and prior to executing any other call related to hybrid messaging. All hybrid messaging methods called prior to service starting (except for ConfigureService which should be called before it and as early in the application life cycle as possible) will return with an error.

RequestVerification client action

Input parameters : MSISDN (phone number). 

Only required once for each user using the application with the sdk implemented. Format : [00_countrycode_PhoneNumber  ] ex: 0032465123549

**IMPORTANT**: in order to be able to receive hybrid messaging notifications and to be able to fetch older messages from the server, the device's phone number (MSISDN) has to be verified at least once after the app's installation. Default phone number verification method is by the means of sending a one-time PIN via SMS.

Returns current [DeviceRegistrationStatus]

RequestVerificationVoiceCall client action

Requests the phone number verification via voice call. Typically serves as a fallback in case if the default SMS-based number verification failed e.g. due to network issues. The requested voice call, if successful, will provide the same PIN code as was originally sent via SMS.

verifyPin client action

Required if a RequestVerification is Required

Verifies the PIN typically entered by the user after previously receiving it in an SMS for the purpose of phone number verification.

Returns current [DeviceRegistrationStatus]

GetVerificationStatus client action

Requests current verification status from the current MSISDN (phone number)

GetMessages client action

Optional Input parameters: 

• Limit: amount of messages to retrieve
• Offset: offset from which messages to retrieve

Returns the messages that have been sent to the particular MSISDN number using Hybrid Messaging (either all of them ever since the number has been registered with Hybrid Messaging or a subset of those depending on the provided limit and offset values)

GetDeviceId client action

Returns a device ID value as used by the Hybrid Messaging system for device identification

GetMsisdn client action

Returns the value of the msisdn number registered with the hybrid messaging system

SetDevelopment client action [IOS DEV Only]

Required parameters: true or false

Sets development mode for iOS, which will use Development Sandbox for push messages in that case.

GetDeviceRegistrationStatus 

Get the status if the MSISDN is registred with the App configured on CM portal.

Returns a DeviceRegistrationStatus code, possible codes:

• Unverified
• Waiting_For_Pin
• Last_Pin_Verification_Failed
• Pin_Verified
• Invalid
• Unknown

Implementation Flow

There is a basic webblock available which calls the required client actions for HybridMessages.

The Required client actions to make hybrid messaging work are (in the onReady of a screen/layout):

• ConfigureService client action (ConfigureCM and StartMessagingService methods/javascript)
• RequestVerification (only required once for the user using the app)
• verifyPin (if requestVerification was required)

Example of an onReady:

• ConfigureService
• getDevice (optional, called in the successCallback from startMessaginService)
• getMsisdn (optional, called in the successCallback from startMessaginService )
• getVerificationStatus(optional, called in the successCallback from startMessaginService)  : based on the return, a RequestVerification and VerifyPin might be required. If for example the MSISDN(phonenumber) has not been verified yet, this example screen might appear: