cordova-plugin-ms-azure-mobile-engagement

Cordova plugin for Azure Mobile Engagement

Introduction

This plugin integrates the Azure Mobile Engagement (AZME) SDK into your Cordova Application. It supports both reporting and push features.

Please refer to the Azure Mobile Engagement documentation for more information about the various AZME concepts.

Supported Platforms

• iOS
• Android
• Windows 10 Universal & Windows 8.1

Supported Framework

• Cordova
• PhoneGap
• CocoonJS
• CrossWalk

Installation

To install the plugin, just add it to your Cordova project using your proper AZME credentials through Cordova variables.

cordova plugin add cordova-plugin-ms-azure-mobile-engagement --variable KEY=<value>

Generic Variables

• AZME_ENABLE_PLUGIN_LOG : true|false, enable logs from the Cordova Wrapper (recommended for development)
• AZME_ENABLE_NATIVE_LOG : true|false, enable logs from the AZME native SDK
• AZME_ACTION_URL : the url schemes of your application when using redirect actions in your campaign. Must be the url prefix without :// (ex: myapp to handle urls such as myapp://shop)

iOS Variables

• AZME_IOS_CONNECTION_STRING : the iOS connection string (to retrieve from the AZME portal)
• AZME_IOS_REACH_ICON : the icon used for reach notification : must be the name of the resource with its extension (ex: mynotificationicon.png), and the icon file must be added into your iOS project with XCode (using the Add Files Menu)

Android Variables

• AZME_ANDROID_CONNECTION_STRING : the Android connection string (to retrieve from the AZME portal)

• AZME_ANDROID_REACH_ICON : the icon used for reach notification

  • must be the name of the resource without any extension, nor drawable prefix (ex: mynotificationicon)
  • the icon file must be copied into your android project with its extension (ex: platforms/android/res/drawable/mynotificationicon.png)

• AZME_ANDROID_GOOGLE_PROJECT_NUMBER : the project number used as the GCM (Google Cloud Messaging) sender ID

Windows Variables

• AZME_WINDOWS_CONNECTION_STRING : the WINDOWS connection string (to retrieve from the AZME portal)

NB

• Only the AZME_*_CONNECTION_STRING are required : all the other variables are optionals.

Example:

cordova plugin add cordova-plugin-ms-azure-mobile-engagement --variable AZME_IOS_CONNECTION_STRING=AZME_IOS_CONNECTION_STRING --variable AZME_ANDROID_CONNECTION_STRING=AZME_ANDROID_CONNECTION_STRING 

To remove the plugin,

cordova plugin rm cordova-plugin-ms-azure-mobile-engagement

Location Reporting

Location reporting can be activated by using two additional variables to define which location to report, and whether this reporting should be performed while the application is running in the background:

• --variable enableLocation : lazyarea|realtime|finerealtime
• --variable backgroundReporting : true|false

Example

cordova plugin add cordova-plugin-ms-azure-mobile-engagement --variable enableLocation=realtime --variable backgroundReporting=true

Remarks

• By default, location report is being deactivated.
• Internally, some additional plugins are being added to your project, but they will be automatically removed when the AZME plugin is being removed
  • cordova-plugin-ms-azure-mobile-engagement-lazyarea-location
  • cordova-plugin-ms-azure-mobile-engagement-runtime-location
  • cordova-plugin-ms-azure-mobile-engagement-fineruntime-location
  • cordova-plugin-ms-azure-mobile-engagement-foreground-reporting
  • cordova-plugin-ms-azure-mobile-engagement-background-reporting
• If you are targetting AndroidM, your application needs to call Engagement.requestPermissionsat some point (cf. below)
• For IOS, you can also add --variable AZME_IOS_LOCATION_DESCRIPTION : <desc> to define the message that will be displayed to the end user in the permission dialog
• Not supported on Windows

Push Notification Support

To enable Reach, you need to call Engagement.initializeReach() to register the application to receive push notification.

Engagement.initializeReach( _openURLHandler, _dataPushHandler, [_success], [_failure]);

Params

• _onOpenURLHandler: the function to be called when an application specific URL is triggered (from a push campaign for example). The URL scheme must match the one defined in the $AZME_ACTION_URL setting
• _dataPushHandler: the function handler to receive the data push. The function needs to accept two parameters : the category , and the body

Example

    onOpenURL = function(_url) {
            console.log("user triggered url/action "+_url);
        };
     onDataPushReceived = function(_category,_body) {
            if (_category=="png")
                str += '<img src="data:image/png;base64,'+_body+'" width="128" height="128" />';
            else
                str += _body;
            // ...
        };  
     Engagement.initializeReach(onOpenURL,onDataPushReceived);

Notes

• on IOS, this call will ask the user to autorize push notifications for your application, so it is recommended to trigger that call at the proper time (ie: once the users are engaged into your application)
• If the body contains non-text data, it will be received encoded in base64 format
  • If the data is an image, it can be directly displayed using the prefix data:image/png;base64 (cf. example)
  • If you want to extract the data bytes, you would need to use the btoa() function to convert base64 to binary
• Reach is not available on Windows yet!

Public Interface

Once the deviceready event has been triggered by the Cordova framework, a Engagement object is available to interact with the native AZME SDK.

• Engagement.startActivity
• Engagement.endActivity
• Engagement.sendAppInfo
• Engagement.startJob
• Engagement.endJob
• Engagement.sendEvent
• Engagement.getStatus
• Engagement.requestPermissions
• Engagement.sendSessionEvent
• Engagement.sendSessionError
• Engagement.sendError
• Engagement.sendJobEvent
• Engagement.sendJobError
• Engagement.sendCrash
• Engagement.isEnabled
• Engagement.setEnabled

Engagement.startActivity

Start a new activty with the corresponding extra infos object.

Engagement.startActivity(_activityName, _extraInfos,[ _success], [_failure]);

Params

• _activityName: the name of the activity
• _extraInfos: a json object containing the extra infos attached to this activity

Engagement.endActivity

Ends the current Actvity. Would trigger a new session on the next startActivity

Engagement.endActivity([ _success], [_failure]);

Engagement.sendEvent

Send an event with the corresponding extra infos object.

Engagement.sendEvent(_eventName, _extraInfos,[ _success], [_failure]);

Params

• _eventName: the name of the event
• _extraInfos: a json object containing the extra infos attached to this event

Engagement.startJob

Start an new job with the corresponding extra infos object.

Engagement.startJob(_jobName, _extraInfos,[ _success], [_failure]);

Params

• _jobName: the name of the job
• _extraInfos: a json object containing the extra infos attached to this job

Engagement.endJob

End a job previously created by startJob

Engagement.endJob(_jobName,[ _success], [_failure]);

Params

• _jobName: the name of the job

Engagement.sendSessionEvent

Send a session event

Engagement.sendSessionEvent(_eventName, _extraInfos ,[ _success], [_failure]);

Engagement.sendSessionError

Send a session error

Engagement.sendSessionError(_error, _extraInfos ,[ _success], [_failure]);

Engagement.sendError

Send an error

Engagement.sendError(_error, _extraInfos ,[ _success], [_failure]);

Engagement.sendJobEvent

Send a job event

Engagement.sendError(_eventName, _jobName, _extraInfos ,[ _success], [_failure]);

Engagement.sendJobError

Send a job error

Engagement.sendError(_error, _jobName, _extraInfos ,[ _success], [_failure]);

Engagement.sendAppInfo

Send App Infos atttached to the currente device.

Engagement.sendAppInfo( _appInfos,[ _success], [_failure]);

Params

• _appInfos: the json object containing the app infos to be sent

Engagement.sendCrash

Report crashes manually (Windows Only)

Engagement.sendCrash( _crashId, _crash,[ _success], [_failure]);

Params

• _crashId: the crashid argument is a string used to identify the type of the crash.
• _crash: usually the stack trace of the crash as a string.

Engagement.setEnabled

Active or deactivate the agent

Engagement.setEnabled( _enabled,[ _success], [_failure]);

Params

• _enabled: boolean

Engagement.isEnabled

Returns the status of the agent

Engagement.isEnabled(function(_enabled){...},[_failure]);

Engagement.requestPermissions

Allow the user to autorize the permissions needed for the proper execution of the AZME plugin. By default, there's no need for a additional permissions, but if you've enabled the location reporting, this function must be called to let the user allow the location based permissions (ACCESS_FINE_LOCATION and/or ACCESS_COARSE_LOCATION)

Engagement.requestPermissions([_success], [_failure]);

Notes

• Returns the list of permissions that have been asked, ans whether the user has allowed them or not
• This function does nothing on platforms other than Android M.

Example

Engagement.requestPermissions(function(_ret) {
                console.log("permissions = "+JSON.stringify(_ret));
    });

Engagement.getStatus

Returns information about the AZME plugin.

Engagement.getStatus( _statusCallback, [_failure]);

Params

• _statusCallback: the handler that is passed a json object containing information about the AZME library
• nativeVersion: the version number of the AZME native SDK
• pluginVersion: the version number of the Cordova plugin
• deviceId: the deviceId as defined by AZME
• isEnabled: if the plugin has been enabled (iOS only)
• notificationGranted: if the user has alredy accepted to receive notifications (iOS only)

Example

    Engagement.getStatus(function(_info) {
            console.log("AZME native Version : "+_info.nativeVersion);
            console.log("AZME plugin Version : "+_info.pluginVersion);
            console.log("Device ID : "+_info.deviceId); 
        });

History

3.3.0

• Updated iOS SDK to 4.1.0 (iOS 6 deprecation, iOS 11 support)
• Updated iOS SDK to 4.3.1 (Android O support)

3.2.3

• Updated iOS SDK to 4.0.1

3.2.2

• Fixed location reporting support for Cordova 6.3.x+
• Fixed permissions support when using Fine Location reporting on Android
• Updated Android SDK to 4.2.3
• Updated Windows SDK to 2.0.1

3.2.1

• Added permissionAllowed in getStatus()
• Fixed exception during first run on Windows

3.2.0

• Updated iOS SDK to 4.0.0 to support iOS 10 / XCode 8

3.1.0

• Added Windows support (Analytics only)
• Fixed SendAppInfos on Android
• Added SetEnabled/IsEnabled interface

3.0.2

• Fixed possible duplicate notifications

3.0.1

• Fixed onOpenURL not being called when using a notification with no additional view

3.0.0

• API Breaking Change
  • AZME_ENABLE_NATIVE_LOG/AZME_ENABLE_PLUGIN_LOG instead of AZME_ENABLE_LOG
  • AZME_ACTION_URL instead of AZME_REDIRECT_URL
  • initializeReach instead of registerForPushNotification/onHandleURL/onDataPushReceived
  • Category is set to null instead of None if not defined within a campaign
  • APIs use Engagement.<APIName> convention instead of AzureEngagement.<APIName>
• Added AZME_IOS_LOCATION_DESCRIPTION variable
• Fix Location reporting hooks

2.3.1

• Added Android M Support
• Added reporting functions
• Refactor underlying code to share the same base code with the AZME Unity SDK

2.2.0

• Added location reporting

2.1.1

• Refactor Native <-> JS Bridge

2.1.0

• Added data push support

2.0.1

• Added debug logs

2.0.0

• Upgraded Native Android SDK to v4.1.0
• Upgraded Native iOS SDK to v3.1.0
• Using the ConnectionString instead of the former AppID/SDKKey/Collection

1.0.0

• Initial Release

Open Source Code of Conduct

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.