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.
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>
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 SDKAZME_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
)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)AZME_ANDROID_CONNECTION_STRING
: the Android connection string (to retrieve from the AZME portal)
AZME_ANDROID_REACH_ICON
: the icon used for reach notification
mynotificationicon
) platforms/android/res/drawable/mynotificationicon.png
) AZME_ANDROID_GOOGLE_PROJECT_NUMBER
: the project number used as the GCM (Google Cloud Messaging) sender ID
AZME_WINDOWS_CONNECTION_STRING
: the WINDOWS connection string (to retrieve from the AZME portal)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 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
cordova plugin add cordova-plugin-ms-azure-mobile-engagement --variable enableLocation=realtime --variable backgroundReporting=true
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
Engagement.requestPermissions
at some point (cf. below)--variable AZME_IOS_LOCATION_DESCRIPTION : <desc>
to define the message that will be displayed to the end user in the permission dialogTo enable Reach, you need to call
Engagement.initializeReach()
to register the application to receive push notification.
Engagement.initializeReach( _openURLHandler, _dataPushHandler, [_success], [_failure]);
_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
onOpenURL = function(_url) {
console.log("user triggered url/action "+_url);
};
onDataPushReceived = function(_category,_body) {
if (_category=="png")
str += '<img src="https://github.com/Azure/azure-mobile-engagement-cordova/raw/master/data:image/png;base64,'+_body+'" width="128" height="128" />';
else
str += _body;
// ...
};
Engagement.initializeReach(onOpenURL,onDataPushReceived);
data:image/png;base64
(cf. example)btoa()
function to convert base64 to binaryOnce the deviceready
event has been triggered by the Cordova framework, a Engagement
object is available to interact with the native AZME SDK.
Start a new activty with the corresponding extra infos object.
Engagement.startActivity(_activityName, _extraInfos,[ _success], [_failure]);
_activityName
: the name of the activity_extraInfos
: a json object containing the extra infos attached to this activityEnds the current Actvity. Would trigger a new session on the next startActivity
Engagement.endActivity([ _success], [_failure]);
Send an event with the corresponding extra infos object.
Engagement.sendEvent(_eventName, _extraInfos,[ _success], [_failure]);
_eventName
: the name of the event_extraInfos
: a json object containing the extra infos attached to this eventStart an new job with the corresponding extra infos object.
Engagement.startJob(_jobName, _extraInfos,[ _success], [_failure]);
_jobName
: the name of the job_extraInfos
: a json object containing the extra infos attached to this jobEnd a job previously created by startJob
Engagement.endJob(_jobName,[ _success], [_failure]);
_jobName
: the name of the jobSend a session event
Engagement.sendSessionEvent(_eventName, _extraInfos ,[ _success], [_failure]);
Send a session error
Engagement.sendSessionError(_error, _extraInfos ,[ _success], [_failure]);
Send an error
Engagement.sendError(_error, _extraInfos ,[ _success], [_failure]);
Send a job event
Engagement.sendError(_eventName, _jobName, _extraInfos ,[ _success], [_failure]);
Send a job error
Engagement.sendError(_error, _jobName, _extraInfos ,[ _success], [_failure]);
Send App Infos atttached to the currente device.
Engagement.sendAppInfo( _appInfos,[ _success], [_failure]);
_appInfos
: the json object containing the app infos to be sentReport crashes manually (Windows Only)
Engagement.sendCrash( _crashId, _crash,[ _success], [_failure]);
_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.Active or deactivate the agent
Engagement.setEnabled( _enabled,[ _success], [_failure]);
_enabled
: boolean Returns the status of the agent
Engagement.isEnabled(function(_enabled){...},[_failure]);
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]);
Engagement.requestPermissions(function(_ret) {
console.log("permissions = "+JSON.stringify(_ret));
});
Returns information about the AZME plugin.
Engagement.getStatus( _statusCallback, [_failure]);
_statusCallback
: the handler that is passed a json object containing information about the AZME library
nativeVersion
: the version number of the AZME native SDKpluginVersion
: the version number of the Cordova plugindeviceId
: the deviceId as defined by AZMEisEnabled
: if the plugin has been enabled (iOS only)notificationGranted
: if the user has alredy accepted to receive notifications (iOS only) Engagement.getStatus(function(_info) {
console.log("AZME native Version : "+_info.nativeVersion);
console.log("AZME plugin Version : "+_info.pluginVersion);
console.log("Device ID : "+_info.deviceId);
});
permissionAllowed in
getStatus() SendAppInfos
on AndroidSetEnabled
/IsEnabled
interfaceonOpenURL
not being called when using a notification with no additional viewAZME_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
null
instead of None
if not defined within a campaignEngagement.<APIName>
convention instead of AzureEngagement.<APIName>
AZME_IOS_LOCATION_DESCRIPTION
variableThis 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.