azure-mobile-engagement-cordova/README.md

# Azure Mobile Engagement service has been retired and is no longer available.

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.
```sh
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:
```sh
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,
```sh
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
```sh
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.requestPermissions`at 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.

```javascript
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
```javascript
    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.
```javascript
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
```javascript
Engagement.endActivity([ _success], [_failure]);
```
### Engagement.sendEvent
Send an event  with the corresponding extra infos object.
```javascript
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.
```javascript
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
```javascript
Engagement.endJob(_jobName,[ _success], [_failure]);
```
##### Params
* `_jobName`: the name of the job

### Engagement.sendSessionEvent
Send a session event
```javascript
Engagement.sendSessionEvent(_eventName, _extraInfos ,[ _success], [_failure]);
```
### Engagement.sendSessionError
Send a session error
```javascript
Engagement.sendSessionError(_error, _extraInfos ,[ _success], [_failure]);
```

### Engagement.sendError
Send an error
```javascript
Engagement.sendError(_error, _extraInfos ,[ _success], [_failure]);
```

### Engagement.sendJobEvent
Send a job event
```javascript
Engagement.sendError(_eventName, _jobName, _extraInfos ,[ _success], [_failure]);
```

### Engagement.sendJobError
Send a job error
```javascript
Engagement.sendError(_error, _jobName, _extraInfos ,[ _success], [_failure]);
```

### Engagement.sendAppInfo
Send App Infos atttached to the currente device.
```javascript
Engagement.sendAppInfo( _appInfos,[ _success], [_failure]);
```
##### Params
* `_appInfos`: the json object containing the app infos to be sent

### Engagement.sendCrash
Report crashes manually (Windows Only)

```javascript
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

```javascript
Engagement.setEnabled( _enabled,[ _success], [_failure]);
```
##### Params
* `_enabled`: boolean 

### Engagement.isEnabled
Returns the status of the agent

```javascript
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`)

```javascript
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
```javascript
Engagement.requestPermissions(function(_ret) {
                console.log("permissions = "+JSON.stringify(_ret));
    });
```

### Engagement.getStatus
Returns information about the AZME plugin.
```javascript
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
```javascript
    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](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.