Skip to end of metadata
Go to start of metadata


Getting Started

Accengage SDK allows you to track the execution and display of In-App and to handle Push notifications of your application.

This Phonegap/Cordova documentation explains the various methods available and how to use them.

In order to understand more deeply the features of the SDK, please refer also to the User Guide, as well as native iOS and Android documentations.

Changelog

The full changelog is available here : Changelog Cordova

Download

Current Plugin Version: 1.4.2 (November 2018)

  • Android SDK Version: 3.8.3
    including Google Play Services 15.0.1 (Base, Location, Ads), Firebase 17.0.0 (Core, Messaging), A4SSDK-Beacons (1.3.0) A4SSDK-GooglePlayServices (3.3.0) and Accengage plugin-firebase-messaging (2.5.0)
  • iOS SDK Version: 6.3.2
  • Cordova CLI version required : 8.0.0
  • Cordova Android platform version : 7.1.4
  • Cordova iOS platform version : 4.5.4

Plugin installation:

Link : https://www.npmjs.com/package/com.bma4s.sdk.plugins.cordova

The Cordova plugin is now compatible with FCM.

Integration

Basic Integration

Update the file config/BMA4SCordovaConfig.json with your PartnerID and you privateKey BEFORE preparing/building your app on Cordova.

BMA4SCordovaConfig example:

Please DO NOT copy paste the content of this example (comments are not allowed inside a valid JSON file) Fields with * means REQUIRED

Avoid to simply name your notification icon, "icon" or "android". This could be a problem in case of replacement.

 

Then call cordova prepare or/and cordova build.

Some functions require a function as a callback.

In this doc, this function is always named "theCallback" and can be any JS function.

This callback function always takes only one parameter which can be : the result OR an error.

If an error occurs, you will always get a JSONObject like this one : {"error":"The message of the error"}


Example

You can have a list of all available SDK methods by looking at the following file : your-cordova-app/plugins/com.bma4s.sdk.plugins.cordova/example/example.html

If you want to use this file, please copy the content into your-cordova-app/www/index.html and do not forget to copy our stylesheet too (example/css/example.css).

 

If you still need more information (about methods compatibilities for instance), you can look our JS code at : your-cordova-app/plugins/com.bma4s.sdk.plugins.cordova/www/BMA4S.js

Manage GDPR compliancy

There are two steps for sending user opt-in for data collection to Accengage.

First, there is a parameter that you can override in order to let us know about user opt-in or opt-out for data collection. This parameter is android_optin_data for Android (ios_optin_data for iOS). In your json file set it to true if you plan to send user opt-in to Accengage :

    BMA4SCordovaConfig.json
    BMA4SCordovaConfig.json

    If the parameter "android_optin_data" (or ios_optin_data in case of iOS) is set to "false" or any other value different from "true", our SDK will automatically be launched without the need of calling the "setOptinData" method.

    Then, you MUST call the method setOptinData before any other methods from the Accengage SDK for letting us know the opt-in state of the user. 

    There are 2 states the user can be in : TRUE or FALSE.

    source.js

    If it is TRUE, the SDK will start normally. Otherwise it will not start and no data will be collected.

    Furthermore, you can block or allow the collect of an user's geolocation by calling the method setOptinGeoloc.

    Like the Optin Data, there are 2 states : TRUE or FALSE

    source.js

    Of course, if setOptinData is set to false, the SDK will not be running, and then the state of setOptinGeoloc will not be used.

    Advanced Integration

    Please see platform related (iOS, Android) documentation for more information (methods usage, advanced integration...)


    Push Notifications

    Enable Push Notifications

      As of April 10, 2018, Google has deprecated Google Cloud Messaging (GCM). This gateway will no longer be available to broadcast Push Notifications to your users as of April 11, 2019.
      We highly recommend you to migrate your GCM project to Firebase Cloud Messaging (FCM).
      However if you don't plan to migrate yet, you have to integrate manually our GCM plugin from Cordova 1.4.2.
      To do so, please follow this documentation.

      In order to receive push notifications you need to create a Firebase project first or import your GCM project into Firebase. You can do it either by using Firebase Assistant in Android Studio or by using Firebase console. Check this page for more details.

      Once a new firebase project and an Android app of this project are created, you need to move the google-services.json file into your Android app module root directory.

      Then add your own sender Id to the config/BMA4SCordovaConfig.json file:

      Please see Android Documentation for more information.

      We recommand to use the same version of firebase as our plugin but if you are using or want to use a different one, you may have some trouble with dependencies conflicts.

      You should see the part of the doc about dependencies conflits then.

      Integrate our GCM plugin manually

      Since our Cordova Plugin is compatible with FCM, if you want to continue to use GCM, you'll need to make some change on the file at platforms/android/com.bma4s.sdk.plugins.cordova/hellocordova-build.gradle.

      Please find below an example of what to do :

      To enable push notifications for iOS, edit your config/BMA4SCordovaConfig.json file with the following line: 

      To enable multiple language support for interactive notifications, add the language localization to your project:

      iOS 10 Rich Notifications

      The latest version of the plugin supports iOS 10 Rich Notifications. However, to be able to receive these notifications you'll need to add the corresponding extension and the AccengageExtension framework manually to your project. 

      Please see our iOS Media attachments Documentation for the required steps and more information on this topic.

      Prevent RichPush notifications display

      You can prevent the display of any RichPush notification, by calling: 

      To reenable the RichPush Notifications, you can call:

      You can enable/disable RichPush notifications at any time.

      If you need to know the Rich Push lock status:

      This lock does not affect In-App notifications.

      Tracking

      Events

       

      Important

      To use the additional parameters of the custom events for targeting purposes, they must formatted as a valid JSON string. Only strings are accepted as key. For the value, only strings, numbers and booleans are accepted. Use a timestamp to represent a date.

      If you want to track a custom event use the trackEvent method. Events types below 1000 are reserved for the library internal usage. You can use custom event types starting from 1001.

      Note

      Each event needs to be defined in the Accengage User Interface. Go to Settings > Advanced Settings, and add a new event of type Custom with the code used in trackEvent method. The label is only used for a display purpose.

      Custom events (iOS only)

      Event API has been updated. You can now use this method for example :

      Using Analytics

      You can track specific events like “Add to Cart”, “Purchase” and “Lead”. Here is how to use each of these events.

      Lead

      If you want to send a Lead, you can add to your code:

      Add to Cart

      If you want to track an Add to Cart event, add to your code:

      Note: Currency should be a valid 3 letters ISO4217 currency (EUR,USD,..) and the 2 last arguments are price and quantity.

      Purchase

      If you want to track a Purchase event, you can add to your code:

      Note: Currency should be a valid 3 letters ISO4217 currency (EUR,USD,..) and the last argument is the total price of this purchase.

      Update Device Information

      You can create a device profile for each device in order to qualify the profile (for example, registering whether the user is opt in for or out of some categories of notifications). A device profile is a set of key/value that are uploaded to Accengage server. In order to update information about a device profile, add the following lines to your code:

      Replace “key” and “value” with the segmentation key name and the value you want to set.

      The keys and values must match Accengage user information field names and values to allow information to be correctly updated.

      But please note that they MUST be sent in String format when calling updateDeviceInfo() method !

      New API to Update Device Information

      A new API is available in order to update device information in a more structured manner.

      Date Format

      You can send a date using the updateDeviceInfo method.

      Your date has to be in the following format: “yyyy-MM-dd HH:mm:ss zzz”

      Manually Update Geolocation (Android only)

      Geolocation is automatically updated and sent to our servers if "android_no_geoloc" is false inside BMA4SCordovaConfig.json

      If you want to manually update the current location of the device, you can call:

      Enable/Disable Location Services (iOS)

      You can enable geolocation, geofence and beacon services at any time by calling:

      To disable geolocation, geofence and beacon services, simply use the following:

      Views

      If you want to tag each Fragment/Tabs/Activity and be able to target it, you can use the following code as soon as a view is displayed:

      Where your-view is the name of your view.

      States

      In Accengage Interface, you can “Declare a State” (Applications → Advanced Parameters). States are like browser cookies which can be used to trigger Accengage In-App notifications. You can target one or more states and combine them with Event or ViewTag.

      Example: When event 5000 is triggered and state “search” contains “pizz*”, display a specific In-App.

      The following section explains how to declare certain states with the Accengage SDK.

      Put a State

      You can obtain the name of the state from the Accengage “value” field in Applications → Advanced Parameters → States section.

      In order to put a state, write this code:

      Where "search" is the state name and “myValue” is the value you want to put for this state.

      Subscription Tag

      Subscription tag is a new API used to mark user interest for a particular topic : 

      Example :

      A device tag can contain up to 5 parameters and all parameter key should be different. Parameters should be String, Interger, Boolean, Date.

      As mentionned with the name of the method, setDeviceTag is an update of the Subscription Tag, it will override then the previous information.


      You can set an expiration date for your Subscription Tag by adding the parameter "exp" to the Device Tag where the value is a timestamp for the expiration date :

       

      You can unsubscribe a user to a particular topic with the following code : 

      Example :

      Important

      Please note that this feature is only available through Accengage's API

      For more information please contact our Support Team at http://ticket.accengage.com

      Static Lists

      First of all, to use a Static List, you need to create it on the Accengage User Interface.

      Add the current device to a Static List

      In order to add the current device to a Static List you have to provide a JSONArray containing JSONObjects including each a listId and an optional expireAt expiration date

      Remove the current device from a Static List

      In order to remove the current device to a Static List you have to provide a JSONArray containing JSONObjects including each a listId

      Get subscription status

      You have 2 ways to get the subscription status of the current device.

      Get subscription status of selected lists

      Retrieve the status of all wanted lists, you will need to pass a function in order to retrieve the result (here it's theCallback) :

      Get all subscriptions of the current device

      Retrieve the status of all lists, you will need to pass a function in order to retrieve the result (here it's theCallback) :

       

      As a result, you will get a JSONArray containing some JSONObjects :

      Tracking Facebook

      Add your Facebook AppID in config/BMA4SCordovaConfig.json:

      This will enable Facebook Tracking inside your app, no other step is needed on your behalf.

      Deep Linking

      Retrieve custom parameters from Push/In-App/Geofence/Beacons

      If you want to retrieve custom parameters from Push, In-App or Inbox features, call:

      Each time a Push/In-App is displayed or clicked, you will receive a response like this one:

        Retrieve Push Notification payload

        If you want to retrieve the entire push payload, use the following method:

        Here's a payload example for iOS and Android:

          action can contain:

          categories can contain:

          Only our Android SDK is broadcasting BEACON_NOTIFICATIONS and GEOFENCE_NOTIFICATIONS information to third party developer.

          All parameters including your custom parameters are inside params (here we have a custom param named 'my-key')

          Geofence/Beacons

          For a Geofence/Beacon, you will receive a response like this one :

          Here, we have entered 2 geofences.

          transition :

          • 1 for enter
          • 0 for exit

           

          For a beacon, the key will be

           

           instead of


          More details can be found on Android#RetrievingBeaconinformationwithaBroadcastReceiver

          Stop listening for custom parameters

          If you don't want to retrieve custom parameters anymore, please call:

          In-App Notifications

          Prevent In-App notification display

          If you don't want to display any inapp messages temporarily, you can use:

          This function allows you to enable or disable any In-App notification display. By default, its value is false which means that InApp display is enabled.

          Once Inapp is locked, no In-App visual element will be displayed until unlocked. Please use this function with care!

          Inbox

          Inbox is not yet available in our Cordova Plugin and must be implemented the native way

          For iOS, please see iOS Documentation

          For Android, please see Android Documentation.

          Troubleshooting

          Find your A4SID (or Device ID or Mobinaute ID)

          If you need to get the Accengage Device ID (or "Mobinaute Id") of the user, use the following method:

          Restrict SDK connection

          You can temporarily restrict the connections in order to tell our SDK to stop flushing network requests.

          All requests will be locked until you use setRestrictedConnection(false). In order to know if the connection is restricted for our SDK, please use:

          Specific for Android

          Activate Logs

          To enable logs in the console, you can modify the following value of BMA4SCordovaConfig.json :

          You will have to rebuild your app in order to see the logs

          Dependencies conflicts 

          If you encounter conflicts regarding Google Play Services versions and Firebase versions, you have two possibilities : 

          • use the same versions as our plugin ones
          • override the versions of our plugin

           

          Please find below an example for the second point : 

          You'll have to modify the two following files.

          platforms/android/com.bma4s.sdk.plugins.cordova/hellocordova-build.gradle
          platforms/android/app/build-extras.gradle

          Others

          Please see the Android Troubleshooting and Android Optional Code.

          Specific for iOS

          Activate Logs

          To enable logs in the console, you can use the method :

          To enable logs in the Accengage logging application, please follow this documentation.

           

          AppStore unsupported architectures 

          Accengage's frameworks contains architectures for iPhone simulators (x86_64 and i386). If you try to submit an application that contains these architectures to AppStore, it will be rejected by Apple.

          To fix that behaviour, go on Build Phases on XCode and add a new Run Script Phase. Then paste the content of this script, in order to eliminate simulator architecture slices.

           

          The order of the build phases is important. The Run Script phase must be added after (or placed below) the Copy Files phase.


          Others

          Please see the iOS Troubleshooting.

           

          • No labels