Our documentation is changing, please click here to enjoy it!

Skip to end of metadata
Go to start of metadata

Getting Started

Please visit our new page for Android SDK 3.6.x


"Integrating the SDK into your code" is a mandatory step for Accengage solution to work in your applications.

Android 6.0 (Marshmallow) Permission Request

Our SDK will NOT automatically request permissions.

As soon as you integrate one of our features, you need to declare relative permissions inside your AndroidManifest. These permission requests need to be emplemented on your end. 

For Basic Integration: the only permission you should request when your application starts is LOCATION.

This permission request is optional if you are not using the following feature: Geolocation.


If you are not handling the permission request process, Accengage SDK will not crash and the features that need permissions will be automatically deactivated

Version

You can get the latest OLD or NEW version of the SDK automatically or manually: Download our SDK

If you have an older version, some functions and methods in this documentation may not be available.

For more information, please find the Changelog here.

Summary

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

The Accengage SDK is provided as an Android library that your project can reference to at compile-time.

Java Documentation

See the JavaDoc

Samples

All our samples are available on Github.com

Requirements

To integrate AccengageSDK on Android, you will need the following:

  • The latest versions of the Android SDK.
  • Android Studio to manage your project.
  • Android 2.3 (API9) or above

 

If needed, you can get our 3.4.x SDK if you need to use our SDK in an application with Android min-sdk 4.

 

Login Information

You'll also need an Accengage Partner Id, and a Private Key.

These id are available for registered customers at accengage.com

If you want to enable push notifications in your app, you need a SenderId (also called Google API Project Number) This SenderId must match the Google API Key you use in the Accengage Interface.

Integration

Using React Native? See this Documentation for instructions on using the Accengage SDK as Android Native Module.


Add the SDK to your app

To integrate the SDK, add the dependency for A4SSDK to your app-level build.gradle file:

app-level build.gradle

Integrate the SDK into your code

Modify your activities

To work properly Accengage SDK needs information about activities states, intents starting activities and bundles of these intents. For this reason, all of your activities should be slightly modified. There are two ways to do it:

  • by adding a few lines of code into Activity methods defining the lifecycle of the activity

    Modifying Activity methods
  • by inheriting A4SActivity 

    Changing the parent class on A4SActivity

In case you want to use another Android standard activity, the Accengage SDK provides modified activities :

  • A4SExpandableListActivity
  • A4SListActivity
  • A4SPreferenceActivity
  • A4SNativeActivity
  • A4SAccountAuthenticatorActivity

Modify you application class

If you are using the Application class, we recommend you to extend A4SApplication instead of the standard Application.

Application class
Since our SDK is running on its own process, your methods may be executed twice (once in your app, once in the SDK process). By extending the A4SApplication, you prevent unwanted interactions between the SDK and your App (the SDK process will not execute the code of your Application class).

In case you can not extend A4SApplication, see Sub Classing any Application Type.

Add credentials to your app

A4SSDK must be authenticated and authorized by Accengage servers. That's why you need to add application credentials (Partner ID and Private key) into strings.xml resource file:

strings.xml

The last two parameters presented in the code snippet are used to activate logs and disable geolocation. If you want to use geolocated In-Apps and Pushs, please check out our Geolocation section.

If you need to use different credentials, for example one pair of Partner ID / Private key per country which you would like to target, you should use localized strings: How to localize strings? 

To be able to dynamically provide Partner ID and Private key with code, please check out Custom Credentials Integration section.

Obfuscating with Proguard

Our SDK is already obfuscated and Proguard configuration is packaged in the AAR. 

Using Google Play Services

If you want the SDK to be able to use the Google Play Services features (Google Advertiser ID, Geofencing, Geolocation..), consider using our A4SSDK-GooglePlayServices plugin.

We advise you to integrate the Google Advertiser ID part of the plugin to be able to identify your users through various products.

Your app must integrate the GooglePlayServices library in order for the plugin to work correctly.

Using Splashscreen

If your app is using a Splash screen, make sure to visit our section about how to handle it: Troubleshooting Splash Screen. Otherwise, you might prevent the Accengage SDK from working normally.

If you are encountering difficulties with our SDK, please read the Troubleshooting section for more information.

Test your integration

To test your integration, activate logs and start your application. You will see the following lines in the logcat, meaning the SDK is correctly launched:

After that, go to the Accengage User Interface and create a segment. Then, configure a new In-App. After restarting your application, the In-App should be displayed.

You can then follow our tutorial here on how to use this application.

Sample

A sample app is available on Github: https://github.com/Accengage/accengage-android-sdk-samples/tree/master/AccSample

 

Migration Guide

    Upgrade from version 3.5.x to 3.6.x

    AndroidManifest.xml

    It was needed to add our A4SService in your AndroidManifest along with the SDK configuration. The service declaration is now inside our AAR. You need to remove the A4SService and all meta datas inside it from your AndroidManifest.xml:

    Move the SDK configuration (partnerId, privateKey, senderId, etc...) to your strings.xml:

    strings.xml

    Here is string names for each old meta-data:

    Previous Meta-Data String name Default Value
    com.ad4screen.partnerid acc_partner_id  
    com.ad4screen.privatekey acc_private_key  
    com.ad4screen.senderid acc_sender_id  
    com.ad4screen.logging acc_logging false
    com.ad4screen.no_geoloc acc_no_geoloc false
    com.ad4screen.idsprovider acc_ids_provider  
    com.ad4screen.advertiser_id acc_advertiser_id true
    com.ad4screen.notifications.icon acc_notification_icon  
    com.ad4screen.notifications.accent_color acc_notification_accent_color  
    com.ad4screen.webview.script_url acc_webview_script_url  
    com.ad4screen.location.priority acc_location_priority normal
    com.ad4screen.tracking_mode acc_tracking_mode normal
    com.ad4screen.cache.delay acc_cache_delay 10
    com.ad4screen.unsecurepush acc_unsecure_push true

     

    Using Inbox

    Starting with 3.6.x version, Inbox tracking needs to be implemented by you. If you already use Inbox feature and do nothing, no more statistics will be available.

    Please see our Inbox documentation

    Using Beacons

    The 3.6.x version is not compatible with older 1.0.x plugin version. You need to upgrade to version 1.1.0. For this, add the following dependency:

    Upgrade from version 3.4.x to 3.5.x

    The version 3.5.x Android min-SDK is now 9 (2.3).

    build.gradle

    In your build.gradle, upgrade the android.defaultConfig.minSdkVersion to 9 if necessary:

     

    Using Google Play Services plugin

    The 3.0.1 Google Play Services Plugin is now splitted in 4 parts. AdvertiserId, Location and Push parts do not need any modification.

    If you use Geofences and upgrade from 2.x.x to 3.x.x you need to remove the following lines from your AndroidManifest.xml:

    Previous lines are now in the plugin manifest and will be automatically merged in your own AndroidManifest.

    Using custom notifications template

    If you use custom notifications template, widgets IDs changed:

    • com_ad4screen_sdk_logo -> com_ad4screen_sdk_notification_logo
    • com_ad4screen_sdk_title -> com_ad4screen_sdk_notification_title
    • com_ad4screen_sdk_body -> com_ad4screen_sdk_notification_body
    • com_ad4screen_sdk_picture -> com_ad4screen_sdk_notification_big_picture

     

    Upgrade from version 3.3.x to 3.4.x

    The version 3.4.x now supports only Android Studio. If you are still using Eclipse, please migrate to Android Studio. If it is not possible, please use an older version (like the 3.3.x).

    build.gradle

    Verify the applicationId is set in the project’s build.gradle file:

    Using GCM Push Notifications

    Remove the following lines from your AndroidManifest.xml:

    Previous lines will be automatically merged in your AndroidManifest.xml using the Manifest Merger.

    Using Google Play Services plugin

    The 3.4.x version is not compatible with older 1.6.x plugin versions. You need to upgrade to version 2.0.0. For this, add the following dependency:

    This version uses the InstanceID feature instead of deprecated GCM APIs. It means that you can register yourself to another Sender ID using InstanceID without conflicts with the Accengage Sender ID registration process.

    Using ProGuard

    If you are using ProGuard, the 3.4.x version includes Proguard rules in the AAR. You do not need to include them in your own rules.

    Using Beacons

    The 3.4.x version is not compatible with older 1.0.3 plugin version. You need to upgrade to version 1.0.4. For this, add the following dependency:

    Using Geofences

    Add the following lines in your AndroidManifest.xml file:

    Push Notifications

    Accengage Android SDK (A4SSDK)  supports different cloud messaging solutions for push notifications: FCM (Firebase Cloud Messaging), GCM (Google Cloud Messaging) and ADM (Amazon Cloud Messaging). For each solution there is a corresponding plugin used by the SDK to receive push notifications:

    Cloud Messaging solutionAccengage PluginDependecy
    FCMplugin-firebase-messagingfirebase-messaging:11.0.4
    GCMplugin-play-services-pushplay-services-gcm:11.0.4
    ADMA4SSDK-Plugin-Amazonamazon-device-messaging-1.0.1

    Since FCM is the new version of GCM, it's recommended to use plugin-firebase-messaging plugin instead of plugin-play-services-push

    Sizes of the SDK and its plugins (without dependencies) are presented in the table below:

     Size in an app, KB
    A4SSDK502
    plugin-firebase-messaging1.8
    plugin-play-services-push1.7
    plugin-play-services-base1.6
    plugin-play-services-location3
    plugin-play-services-geofence6.3
    plugin-play-services-advertiserid1.5
    A4SSDK-Plugin-Badger5
    A4SSDK-Plugin-Beacons11
    A4SSDK-Plugin-Amazon2.2

      FCM Notifications Setup

      Add Firebase to your app

      Before integrating the SDK and plugin-firebase-messaging plugin into your Android application to receive push notifications you need to create a Firebase project first. 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 yout Android app module root directory and modify your build.gradle files to use google-services plugin. This plugin handles automatically the google-services.json file and adds necessary information about the Firebase project into your Android Studio project while building it.

       

      Use Firebase Assistant in Android Studio to connect your project to Firebase and update the google-services.json file.

       

      Note! You don't need to click on the button 'Add FCM to your app' to add FCM library firebase-messaging. It will be added later.

      If you have already added FCM to you project please check that the version of firebase-messaging library is 10.2.6.

      app-level build.gradle

      Also you may simply remove the line above with firebase-messaging because the FCM library is added automatically with the correct version number when  Accengage plugin-firebase-messaging plugin is integrated in the project.

      Add plugin-firebase-messaging to your app

      You should add Accengage plugin-firebase-messaging plugin to be able to receive FCM/GCM push notifications:

      app-level build.gradle

      The plugin depends on the firebase-messaging:10.2.6 library, so you don't need to add it by your self. However you have to add the dependency for firebase-core:10.2.6 library to avoid conflicts between firebase versions.

      app-level build.gradle

      Add Firebase Server key and Sender ID to Accengage dashboard

      Accengage servers need Server API key and Sender ID of your FCM/GCM project to send push notifications. Copy and paste them from Firebase console to Accengage dashboard.

      Add credentials to your app

      Before testing push notifications you need to add FCM/GCM Sender ID into strings.xml resource file:

      strings.xml


      Sample

      The sample application receiving push notifications from Accengage dashboard and Firebase console is available on github.

       

      GCM Notifications Setup

      Get API Key and Sender ID from Google

      1. Go to the Google Services Interface (you will need a gmail account).
      2. Press the "Pick a platform" button.
      3. Follow the instructions and fulfill the requiered info.
      4. Select the cloud messaging service and hit "Generate configuration files"
      5. Congratulations, the next screen will provide you with your Google API Key as well as with the sender ID

      Configure GCM with Accengage User Interface

      1. Go to Accengage User Interface, and to Settings > Manage Application and find your application
      2. Edit your application's settings, and fill the Google API Key box with your own API Key

      Configure the Accengage SDK

      Requirements

      You need a GCM Sender ID (its format looks like this: 670330094152)

      Understand the push notification data flow.

      Adding Push Notifications

      If you want to add push notifications to your app, just add this string:

      strings.xml

      Do not forget to add “gcm:” before your senderID

      If you need to use a gcm sender id for each country you are targeting, use localized resources.

      Adding required permissions

       

      The Accengage SDK will take care of all the GCM events (including Registration, Retrieving Token, ...). You don't need to handle anything by yourself.

      You need to include the following lines inside your <application> tag:

      Do not forget to replace “your-package” used in this example with your own application package

      Manual GCM Registration

      If you do not want let the SDK to register to GCM, remove the senderId's meta-data com.ad4screen.senderid in the A4SService <service> tag.

      Then send us your GCM Registration token with the following method:

      Make sure to send us your GCM Registration token everytime your application is launched.

      Configuring Accengage interface

      In the Accengage interface, you will need to update your application by going to Settings > Manage your applications and edit your app.
      You will need to enter your Google API Key (see here: Access Key) in the right field. This key -also called Key for Server apps-has a format that looks like this: "AIzaxxxxx...."

      Using GCM with Google Play Services

      If you use Google Play Services in your app, and/or if you want our SDK to use Google Play Services library to register/unregister to GCM (which is a new method recently added by Google), Please take a look at our Google Play Services plugin

      Sample

      A sample is available on Github: https://github.com/Accengage/accengage-android-sdk-samples/tree/master/AccSample

      ADM Notifications Setup

      Get credentials from Amazon

      To be able to receive notifications on Amazon products (like Kindle Fire), you need to retrieve the OAuth Credentials and API Key.

      To do this, please follow these instructions Getting Your OAuth Credentials and API Key.

       

      When this is done, go to Security Profiles and choose the Security Profile associated with your application. In the General tab, get the Client ID and Client Secret:

      Go to the Android/Kindle Settings tab and store your key in a file named api_key.txt. This will be used later.

       

      Configure ADM with Accengage User Interface

      1. Go to Accengage User Interface, and to Settings > Manage Application and find your application

      2. Edit your application's settings, and check Amazon checkbox. Then, fill Amazon Client ID with your own Client ID and Amazon Client Secret with your own Client Secret :

      Configure ADM with your app

      Add Amazon Plugin with Gradle

      To be able to receive ADM Notifications, you need to integrate our Amazon Plugin with Gradle.

      Add API Key

      To be able to receive ADM Notifications, you need to add a valid API Key in your application. To do this, just add the api_key.txt file from Get credentials from Amazon part and place it in the assets folder.

       

      More information here.

       

      Notification Icon

      By default, we are using your launcher icon as a logo for your notifications.

      However, since Android KitKat, Google guidelines indicate that you must use a white and transparent flat icon

      If you created such icon, you can indicate its location to our SDK by adding the following string:

      Please note that "your_icon_name" is the name of the icon without extension and/or path. For instance, if you want to use drawable/ic_action_search.png, please replace "your_icon_name" by "ic_action_search"

      Notification Accent Color

      In order to be compliant with the new Lollipop notifications, you can now define an accent colour for your notifications.

      To indicate to our SDK that it should use your accent colour, add the following string:

      Your accent colour can be a ARGB/RGB colour like the one defined in this example.

      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.

      This lock does not affect In-App notifications. 
      To activate the lock on the In-App notifications, follow this link: In-app Advanced

      Using Popup

      If you are planning to use our "Show Popup" option, please note that in order to match the Google guidelines for Android, we advise you to customise the behaviour and appearance of the pop-up notifications. Customise the behaviour and appearance of the pop-up notifications.

      Testing

      In order to test your integration, you can create a segment with your device id and try to activate a push targeting a segment.

      To easily retrieve your Device ID required to enter in the Accengage User Interface, download, install and launch the following application:

      Multiple push providers

      If you have other push systems integrated into your app that are using GCM too, here is how to proceed in order to get them working too:

      Remove com.ad4screen.sdk.GCMHandler and any other GCM <receiver> declaration from your AndroidManifest.xml

      Create your own GCM receiver which extends com.ad4screen.sdk.GCMHandler and overrides the onPushReceive method

      MyGCMHandler.java

      OnPushReceive will ONLY be called for push notifications that doesn't come from our Web Interface.

      Finally, declare your receiver inside AndroidManifest.xml:

      AndroidManifest.xml

      Do not forget to replace “your-package” used in this example with your own application package

      Custom notification sounds

      If you want to add a custom sound for your notifications, please add your mp3 file in the res/raw folder of your application. Then, provide the file name (without the extension) in the Accengage User Interface.

      Manually Handling all pushes

      If you want to completely handle push notifications yourself, you need to override the processPush method, here is the original code:

      MyGCMHandler.java

      Please do not forget to call processA4SPush.

      Notification Channels

      With Android 8.0, a new feature called Notification Channels has appeared. An application targeting API Level 26 or higher needs to add support to notifications channels or notifications will not be displayed.

       

      The Accengage SDK adds support to this feature in versions 3.5.4 and 3.6.1.

      Our SDK includes 6 presets of channels to use our notifications without any efforts. For more informations, please follow our User Documentation. Our presets of channels are created only when receiving a corresponding notification. If you do not want to display our presets of channels, create your own channel and do not use ours.

      Add a new Notification Channel

      Just follow the Android documentation. You will need to use the correct channel identifier when configuring messages in Accengage User Interface.

      Edit an exisintg preset

      You can edit existing presets of channels by overriding correct strings in resource file. For each channel you can edit following options:

      OptionResource name suffixDescription

      Name

      *_nameName of the channel, string
      Description*_descDescription of the channel, string
      Importance*_importance

      Importance of the channel, integer

      Min: 1 / Low: 2 / Default: 3 / High: 4

      Enable Led*_led

      Enable or disable Led display, boolean

      true or false

      Led Color*_led_color

      Color of the Led

      Format #RRGGBB

      Enable Vibration*_vibration

      Enable or disable vibration, boolean

      true or false

      Lockscreen Visibility*_lockscreen_visibility

      Visibility of the lockscreen, integer

      Secret: -1 / Private: 0 / Public: 1

      Sound*_sound

      Sound when notification is displayed

      none, default or resource name in raw folder

      Bypass Do Not Disturb*_bypass_dnd

      Bypass the Do Not Disturb option, boolean

      true or false

      Enable Badge*_badge

      Enable or disable badge for this channel, boolean

      true or false

      Use the following prefix for corresponding channels:

      Channel nameResource name prefix
      General Informationacc_channel_general
      Service Messagesacc_channel_service
      News Messagesacc_channel_news
      Urgent Messagesacc_channel_high
      Low priority Messagesacc_channel_low
      Minimum priority Messagesacc_channel_min

      For exemple, our configuration of the General Information channel:

      strings.xml

      Advanced Push Notifications

      If you want customize buttons, the notification template, the notification builder or understand the back stack mechanism used, please follow our Advanced Push Notifications section.

      Tracking

      Events

      For all other types of events, use the trackEvent method. Events types below 1000 are reserved for the library internal usage.  You can use custom event types starting from 1001.

      To use the additional parameters of the custom events for targeting purposes, they must formatted as a valid json string. Use a timestamp to represent a date. The maximum string size which you can use with the method trackEvent() is limited to 255 characters otherwise the string with an event value will be truncated.

      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.

      Logcat Output

      Using Analytics

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

      Lead

      First, create a Lead to track like this one:

      And send your Lead to A4S Servers:

      Logcat Output

      Add to Cart

      First, you will need to create an item to track, like this one:

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

       

      Now you just need to specify the cart id and give us the item:

      And send to A4S Servers :

      Logcat Output

      Purchase

      You have 2 ways to send a Purchase tracking, with or without an array of Items.

      First, you will need to create a Purchase to track, like this one:

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

       

      If you want to add an array of items belonging to this purchase, you can:

      Note: Don't forget to create each “Item” at first and add them to an "Item[]" array.

       

      Finally, send your purchase to A4S Servers:

      Logcat Output

      Error Logs

      • Failed to send purchase events to server = No internet connection or server is unreachable

      • Request succeeded but parameters are invalid = some of the parameters sent are invalid, please read carefully the log to understand what is wrong

      • Error with this purchase = purchase id you tried to send already exists (already sent). Please note that each purchase event sent should have a distinct purchase id

      Sample

      A sample is available on Github: https://github.com/Accengage/accengage-android-sdk-samples/tree/master/AccEvents

      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. To create these fields, follow the User Guide.

      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”

      Please use the code below to format your date before sending it to Accengage servers:

      Logcat Output

      Error Logs

      • Profile update failed = No internet connection or server is unreachable

      • Request succeeded but parameters are invalid = some of the parameters sent are invalid, please read carefully the log to understand what is wrong

      • Some fields do not exist = You tried to update fields that do not exist inside your app's database scheme. Verify your app configuration and please note that fields are case sensitive

      Views

      Using Tags to identify each Activity

      First, you have to add a tag to your activity in order to define a name for your view that the SDK can refer to.

      By default, when you setup an In-App notification with a banner in the web interface, the SDK will use a default template and an overlay will be added to the bottom of your activity.

      The description above is sufficient for basic integration. For custom integration, please refer to the sections below.

      Using setView to identify each Fragment/Tabs

      If you want to tag each Fragment/Tabs 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.

      Logcat Output

      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.

      Clear a State

      In order to clear a state, just set its value to null:

      Where “search” is the state.

      Logcat Output

       

       

      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, create a new StaticList object:

      Where staticListId is the field "external id" in the Accengage User Interface.

      You can set an expiration date to the current device in order to delete it from the static list once the date is reached:

      When the expiration date is reached, the device will automatically be removed from the static list.

       

      As soon as you have created your StaticList objects, execute the following line:

      or, with a list of StaticList objects:

      Remove the current device from a Static List

      Create a StaticList object:

      Where staticListId is the field "external id" in the Accengage User Interface.


      Then, execute the following line in order to remove the current device from selected lists:

      or, with a list of StaticList objects:


      Get subscription status

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

      Get subscription status of selected lists

      First, create a StaticList object:

      Where staticListId is the field "external id" in the Accengage User Interface.

      Create a List of StaticList:

      Create a Callback to get the result or errors (for instance : no network, invalid id, ..):

       

      Finally, retrieve the status of all wanted lists:

      Get all subscriptions of the current device

      Create a Callback to get the result or errors:


      Finally, execute the following line:


      Tracking Webview

      In case you are using an A4SWebview and would like to access the SDK tracking tools, you will need to use a different method in order to interact with the webcode inside of the webview.

      A4SWebview

      To use the tracking functions, you cannot use a standard Webview but instead, an A4SWebview available in the Accengage SDK. Here is an example of how to instantiate it in Java:

       

      Or in the xml file:

       

       

      Events

      To fire a custom event in you javascript code, you can use the trackEvent method in this way:

      Using Analytics

      The main tracking events are also available through the “A4S” javascript interface. Here is how to set them:

       

      “data” is a Json and its associated objects will be rebuilt by the SDK, therefore, the existing object templates must be correctly written. Here are the mentioned templates:

      Purchase

      Cart

      Lead

       

      Update Device Information

      When you want to use the updateDeviceInfo function inside your webview, you have to use the "A4S" object that makes the interface between your web code and the Accengage SDK like this:

      “data” is the Json representing the updateDeviceInfo you want to send :

       

       

      Update Device Information from WebView's content

      You can send Update Device Information with some parameters in a URL.

      Generate a JSON with each key/value:

      Add this encoded JSON as the bma4sudi value in any URL:

      The JSON must be encoded.

      When the user clicks on the previous URL, he will be redirected to Google and 2 Update Device Information will be executed.

       

      Views

      In javascript, inorder to target a specific view, you need to use the setView method:

      “view” is the name of the view being displayed to the user.

      Javascript injection

      When an A4SWebview is started, it will automatically run a javascript file added by Accengage as soon as the page is fully loaded. Though it is the default behaviour, it is possible to replace this script URL with your own script in the following way:

      Using WebviewClient

      If you want to use a WebviewClient in order to add custom behaviour to the A4SWebview methods, you should proceed like this:

      The methods you will override in you WebviewClient will be called from the A4SWebview.

      Close WebView from WebView's content

      You can close the WebView with a specific URL inside the WebView. First, you need to manage the close action.

      Next, in your HTML content, add the bma4sclose key in the closing URL, for example:

      Deep Linking

      Retrieving In-App/Push/Inbox and other Custom Parameters with a BroadcastReceiver

      In the Accengage Interface, you can specify some custom parameters linked to click and/or display actions. The Accengage SDK sends a broadcast each time an item is displayed or clicked on in order to give you back these parameters. Here is how to retrieve your custom parameters from any kind of notification

      Create a BroadcastReceiver

      Create a BroadcastReceiver like this one:

      In this example, the BroadcastReceiver is named InAppHandler. The String “myKey” is the key you defined in the Accengage User Interface. Now, “myCustomParam” will contain the value of this key.

      Modify your AndroidManifest.xml

      Add the receiver to your AndroidManifest.xml inside of the <Application> tag:

      Here are the categories you can subscribe to:

      • com.ad4screen.sdk.intent.category.PUSH_NOTIFICATIONS for RichPush Notifications
      • com.ad4screen.sdk.intent.category.INAPP_NOTIFICATIONS for In-App Notifications
      • com.ad4screen.sdk.intent.category.INBOX_NOTIFICATIONS for Inbox Notifications

      Here are the actions you can subscribe to:

      • com.ad4screen.sdk.intent.action.CLICKED
      • com.ad4screen.sdk.intent.action.DISPLAYED
      • com.ad4screen.sdk.intent.action.CLOSED

      You can now add your code to the BroadcastReceiver in order to handle your custom params.

      Using URL Schemes

      Here is an example of using URL schemes in your app

      AndroidManifest.xml

      If you want, you can retrieve data from URL scheme using the code below:

      Update Device Information from URL Scheme

      You can send Update Device Information with some parameters in a URL Scheme.

      Generate a JSON with each key/value:

      Add this encoded JSON as the bma4sudi value in a URL Scheme that redirect to your application (if you redirect to a URL Scheme that do not integrate the Accengage SDK, the bma4sudi parameter will not be processed):

      The JSON must be encoded.

      When the user clicks on the previous URL Scheme, he will be redirected to your app and 2 Update Device Informations will be executed.

      Sample

      A sample is available on Github: https://github.com/Accengage/accengage-android-sdk-samples/blob/master/AccSample/app/src/main/java/com/accengage/samples/coffeesample/receivers/CustomsParametersReceiver.java

       

      In-App Notifications

      The Accengage SDK provides you with notifications display without any additional code to write in order to support them.

      There are five different kinds of inApp notifications:

      • Text: an InApp notification that appears as a view with a height of 50 containing a title and a text body.
      • WebView: an InApp notification that appears as a view with a height of 50. It contains a webView that displays the content of a URL.
      • Text Interstitial: appears in full screen and contains a title and a text body.
      • WebView Interstitial: it appears in full screen and contains a webView that displays the content of a URL which is clickable.
      • WebView Interstitial with NavBar: appears in full screen and contains a webView that displays the website target of a URL. It also displays a navigation bar and can be browsed.

      In order to match the Google guidelines for Android, we advise you to customise the behaviour and appearance of the pop-up notifications.
      Please see Customising Pop-up / Customising interstitial.

      Prevent In-App notification display

      If you don't want to display any inapp message 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!

      Update Device Information from In-App's content

      You can send Update Device Information with some parameters in a URL.

      Generate a JSON with each key/value:

      Add this encoded JSON as the bma4sudi value in any URL:

      The JSON must be encoded.

      When the user clicks on the previous URL, he will be redirected to Google and 2 Update Device Informations will be executed.

      Close In-App from In-App's content

      You can close the In-App with a specific URL inside the In-App. In your HTML content, add the bma4sclose key in the closing URL, for example:

      Advanced In-App Notifications

      If you want customize deeper your In-App Notifications, please follow our Advanced In-App Notifications section.

      Inbox

      The Inbox feature has been created in order to display delayed messages to your users. There are lots of formats for those messages, including text, webpage, and richpush with or without buttons.

      Those messages and buttons interact directly with the Accengage SDK. E.g. your message can include an event button, trigger an URL Scheme, or display a banner/interstitial when the user opens a message.

      If you want to use this feature, the Accengage servers will send all the messages information to your app, but you will need to handle the display yourself.

      Basic Integration

      With Accengage Inbox you can:

      • Subscribe/Unsubscribe to Inbox Messages on a device
      • Get messages and display them in your own template
      • Update messages on the Accengage servers (Read/Unread/Archive)

      Get Messages

      Use the following method to retrieve your messages:

      You need a callback to be notified when messages are received. Here is an example of how to define it:

      List Messages

      Now that you have your inbox object filled with messages, it's time to list your messages. In this example, we will just display a toast with the title of each message

      Display a message

      Now that our messages are downloaded, we can safely display them. Then according to the message format, the SDK will either openit itself or give it to you. If the message is returned to your application, a callback will be triggered and you will have to handle the message's display.

      Work with Message Buttons

      A message can have several buttons and here is an example of how to display and interact with them.

      Note: Don't forget to add each button to your layout.

      Update a message

      You can change the status of a message, here is how to do it

      Last step, you need to send all the changes made on this inbox to the Accengage Servers:

      Tracking Integration

      Starting with Accengage SDK 3.6.x, Inbox tracking needs to be manually implemented to match perfectly your own Inbox feature integration in your application.

      If you do not implement the Inbox tracking, no statistics will be available in Accengage User Interface

      Display Tracking

      You can track when a message is displayed. You can choose to display only at the first display or each time the message is displayed. Use the following method:

      Or, if you want to track only for the first display:

      Click Tracking

      You can track when a message is clicked. Use the following method:

      Button Click Tracking

      You can track when a message's button is clicked. Use the following method:

      Sample

      A sample is available on Github: https://github.com/Accengage/accengage-android-sdk-samples/tree/master/AccInbox

      This example contains 2 activities:

      • InboxList → A list displaying the Title, Extract, Date, etc.. of each message, with all status options (Read, Unread, Archive)

      • ShowMessage → An activity which displays a message including buttons

      Geolocation

      Enable Geolocation

      By default, the Geolocation is enable. Just add the following permission above the <application> tag in your AndroidManifest.xml to enable the GPS:

      AndroidManifest.xml

      Disable Geolocation

      The permission: “android.permission.ACCESS_FINE_LOCATION” is optional.

      If you don't want to use the SDK built-in geolocation or if you prefer updating the location using your own way, please add the following string:

      strings.xml

      As soon as Accengage geolocation is disabled, you can manually update the device's locations using:

       

      Location parameter must be an android.location.Location object.

      This way, you will be able to use geolocated In-App and Push.

      If you are experiencing some difficulties, please check out our Troubleshooting section.

      Handling GPS battery consumption

      By default, the SDK will always be on and constantly get the users' GPS location. There are two ways you can use to change this behaviour :

      Manually updating geolocation

      It is possible to permanently disable the geolocation and to update it only when you need it using this method :

      Google Play Services

      We strongly encourage you to integrate our Google Play Services plugin allowing you to get the geolocation using the most optimised battery consumption. In that way, our SDK will use the FusedLocationProvider in order not to use the GPS when unnecessary. For further explanation, please find the official documentation here.

      Once the Google Play Services are successfully integrated, you'll be able to define a priority to save battery life vs. diminishing the geolocation accuracy. You'll find more information on this link.

      Geofencing

      Please see our User Guide to know what Geofencing is.

      Our Google Play Services Plugin and Google Play Services library are required.

      Geofencing Integration

      No modifications are required.

      Retrieving Geofencing information with a BroadcastReceiver (Optional)

      Each time a user enters or exits a geofence zone defined in the Accengage User Interface, your app will receive their specific information and you may handle them the way you want.

      Create a BroadcastReceiver

      To receive them, you should first create a BroadcastReceiver like this one:

      GeofenceReceiver.java

      Modify your AndroidManifest.xml

      Now, we have to add our “GeofenceReceiver” class to the AndroidManifest.xml in order to allow the SDK to trigger it when needed:

      AndroidManifest.xml

      Retrieving Geofences from ContentProvider

      Since the version 3.5.0 geofences could be retrived from ContentProvider using A4SContract with specified URI. The code snippet instantiating a CursorLoader is shown below:

      From version 3.5.0

      For more details please see A4SGeofences sample (v3.5.0 is required) allowing to list geofences and sort them by name, distance, radius, detected count,... in ascending/descending order.

        

      Sample

      A sample is available on Github: https://github.com/Accengage/accengage-android-sdk-samples/tree/master/AccGeofences 

       

      Beacons

      With this plugin, our SDK will be able to detect beacons around a user.

      As soon as you have imported your beacons into our interface, our SDK will listen for these beacons and specific actions can be triggered:

      • In-App displays
      • Local Notifications scheduling

      For instance, you can define a Local Notifications display 10 seconds after the user has "entered" a beacon zone and another one when the user has "exited" the zone.

      Beacons Integration with Gradle

      To integrate Beacons feature, you just need to follow instructions in the Beacons plugin page.

       

      Retrieving Beacon information with a BroadcastReceiver

      Each time our SDK detects a beacon defined in the Accengage User Interface, your app will receive their specific information and you may handle them the way you want.

      Create a BroadcastReceiver

      To receive them, you should first create a BroadcastReceiver like this one:

      BeaconReceiver.java

      Modify your AndroidManifest.xml

      Now, we have to add our “BeaconReceiver” class to the AndroidManifest.xml in order to allow the SDK to trigger it when needed:

      AndroidManifest.xml

      Sample

      A sample is available on Github: https://github.com/Accengage/accengage-android-sdk-samples/tree/master/AccBeacons

      Optional Code

      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:

      Set a tracking mode

      If you need it, tracking can now be restricted in order to be compliant to the most severe privacy rules. This is not needed for most integrations

      Add the following string:

      strings.xml

      The default mode is “Normal” and you don't need this meta-data if you want to use Normal mode. But, if you want our SDK to be more respectful of the users privacy, you can set the value to “Restricted”

      Please note that if you use “Restricted” mode, some advanced targeting functionalities may not be available

       

      Set cache delay

      If you want the SDK network requests to be executed more or less often, you can set a custom delay for our cache system.

      Add the following string:

      Where 15 represents the delay in seconds before each execution of cached requests.

      Troubleshooting

      Activate Logs

      Something doesn't work? You can enable logging in order to see what is going on.

      To do so, simply add the following string:

      strings.xml

      Plus, you can disable the toast displayed when application is started (because of UI Automation for example):

      strings.xml

      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:

      Stopping the SDK

      If a user wants to opt-out from tracking, you can use this static method:

      Where "this" is any Android context like: Application, Activity, BroadcastReceiver...

      If you want to know whether the user is being tracked or not, use the following static function:

      The "do not track" mode, while activated, will disable all SDK functionalities (tracking, push notification reception, in-app messages, notification statistics...).

      SplashScreen

      Please note that the Accengage SDK must be integrated in the SplashScreen like other Activities.

      The Activity after the Splash Screen have to be launch after the A4S.startActivity() to be able to process the Push Action. For exemple, you cannot redirect directly in the onCreate() method.

      You also have to use setPushNotificationLocked(true) and setInAppDisplayLocked(true) in the OnCreate() method of your SplashScreen and use setPushNotificationLocked(false) et setInAppDisplayLocked(false) on your next Activity.

       

      Some RichPush issues are du to mistakes in the SplashScreen.

      If you have some trouble with your SplashScreen or your RichPush, please take a look at this documentation: Click here

      How to find the SDK version you're using?

      There are two main ways of finding this version and the first one is programmatically. You can access the static variable "SDK_VERSION" in the Constants Class like this:

      The second way is to find the version directly inside the Logs of the app. To do so, make sure that you activated them, launch your app and read the logs.

      The very first line will look like this:

      Of course, 
      "A3.1.2" is an example and the value you will get here is the version number of the SDK you integrated

      How to visualize network requests from Accengage SDK ?

      Since SDK 3.1.8 and 3.2.2, we added tags to network requests to be able to visualize them through DDMS Network Statistics, for example :

      The Accengage SDK uses the 0x00413453 tag.

      DeviceInfo doesn't contain IDFV

      You are facing to those logs repeating again and again ?

      This issue can be due to the use of the annotation @UseA4S. Indeed, we noticed that this plugin may not work with the new Android compiler versions.

      This feature will be removed in the further versions of the SDK. Please, use a manual integration instead of the annotation pluging integration.

      Disable Badges (3.5.0+)

      If you want to disable Badges feature (because too many permissions are asked for example), exclude our Badge plugin from the Accengage SDK dependency:

      Fullscreen Activity with notification and navigation bar

      Your InApp appears under your notification bar and your navigation bar ? Here are two solutions :

      1°) You can use the InApp display customization to include your inapp into a specific view in your layout.

      2°) You can use our method A4S.setOverlayPosition(layoutParams) to add margin to the inapp like that :

       

       

        Plugin - Google Play Services

        This plugin allows the SDK to:

        • Register/Unregister to GCM using GooglePlayServices (official and recommended Google's method)
        • Retrieve and send to Accengage the Google Advertiser ID (IDFA) automatically
        • Geolocation using GooglePlayServices (SDK 3.1.0+). Usefull about power comsumption.
        • Geofencing using GooglePlayServices (SDK 3.1.0+)

        Changelog

        3.4.0 - 10 January 2019

        • Update GPS libraries and target Android API 28

        3.3.0 - 26 July 2018

        • Update play services version to 15.0.1
        • Now requires Accengage SDK 3.8.0

        3.2.0 - 07 May 2018

        • Now requires Accengage SDK 3.7.0

        3.1.4 - 02 March 2018

        • Upgrade to Google Play Services 11.8.0

        3.1.3 - 06 October 2017

        • Target Android API 27
        • Upgrade to Google Play Services 11.4.2
        • Fixed a dependency name in plugin-play-services-advertiserid-3.1.2.pom 

        3.1.2 - 06 October 2017

         
        • The library play-services-ads is removed from dependencies (the size of the dex file is reduced by ~1.2 MB) 

        3.1.1 - 09 august 2017

        • Upgrade to required Google Play Services 11.0.4
        • Downgrade to required Accengage SDK 3.5.4
        • Android O compatibility

        3.1.0 - 26 june 2017

        • Upgrade to required Google Play Services 10.2.6
        • Upgrade to required Accengage SDK 3.6.0
        • Min Android SDK is now 14

        3.0.3 - 26 june 2017

        • Upgrade to required Google Play Services 10.0.1
        • Upgrade to required Accengage SDK 3.6.0

        3.0.2 - 04 november 2016

        • Upgrade to required Google Play Services 9.6.1
        • Upgrade to required Accengage SDK 3.5.1
        • Build with gradle 2.2.1

        3.0.1 - 05 august 2016

        • Upgrade to required Google Play Services 9.4.0
        • Upgrade to required Accengage SDK 3.4.1

        3.0.0 - 23 june 2016

        • Upgrade to required Google Play Services 9.0.2
        • Upgrade to required Accengage SDK 3.4.0
        • Split plugin in differents plugins like Google Play Services

        2.0.0 - 14 april 2016

        • Upgrade to Google Play Services 8.4.0
        • Use InstanceID API for GCM Registration
        • Geofences optimisations

        1.6.6 - 04 may 2016

        • Upgrade to required Accengage SDK 3.3.1
        • Upgrade to required Google Play Services 8.4.0

        1.6.5 - 05 february 2016

        • Add com.google.android.gms:play-services-ads dependency to fix a NoClassDefFound

        1.6.4 - 29 january 2016

        • Replace the Jar with an Aar available on JCenter for an easier integration and a better dependencies management
          Known issue:
          • NoClassDefFoundException: Upgrade to version 1.6.5 or add:

        1.6.3 - 13 november 2015

        • Fixed compilation error when used with Google Play Services 8.1/8.3 + Proguard (Please see Android issue #187483)

        1.6.2 - 15 october 2015

        • Fixed GCM unregistration process for new versions of GPS

        1.6.1 - 8 october 2015

        • Fixed some issues with some Backoff behaviors

        Plugin installation

        Minimum Required SDK Version: 3.6.0

        JCenter link : https://bintray.com/accengage/maven/plugin-play-services

        The Google Play Services Plugin 3.x.x is splitted in 4 parts:

        • Push Plugin: Add the possibility to use InstanceId API to register to pushs. Add the following line in your build.gradle dependencies:

        • AdvertiserId plugin: Add the possibility to get the AdvertiserId. Add the following line in your build.gradle dependencies:

        • Geofence plugin: Add the possibility to monitor Geofences. Add the following line in your build.gradle dependencies:

        • Location plugin: Add the possibility to use Google Play Services location. Add the following line in your build.gradle dependencies:

        If you want to use all plugin parts, just add the following line in your build.gradle dependencies:

        Google Play Services Dependencies Used

        Here is the dependencies used in the plugin :

        If you really need to use another version of the google play services, just add those dependencies in your build.gradle file with the version you want.


        Check plugin installation

        In order to know if the plugin works and is used by the SDK, please activate the SDK logs and look for the following line:

        Geofencing Integration

        Please check: Geofencing

        Useful commands

        If you don't need to use Google Advertiser ID, you can disable it by adding this string:

        strings.xml

        You can set a priority to our location plugin:

        strings.xml

        Value can be set to: “normal”, “high”, “low” and “none”.

        This corresponds to the value of the com.google.android.gms.location.LocationRequest setPriority method.

        Default value is “normal”, which corresponds to PRIORITY_BALANCED_POWER_ACCURACY

        Plugin - Firebase

        This plugin allows the SDK to fully support Firebase Messaging

        Changelog

        3.0.0 - 02 July 2010

        • Update firebase version to 18.0.0

        2.5.0 - 26 July 2018

        • Update firebase version to 17.0.0
        • Requires Accengage SDK 3.8.0

        2.4.0 - 07 May 2018

        • Now requires Accengage SDK 3.7.0

        2.3 - 02 March 2018

        • Upgrade to Firebase 11.8.0

        2.2 - 13 December 2017

        • Upgrade to Firebase 11.4.2
        • Target Android API 27

        2.1 - 16 August 2017

        • Upgrade to Firebase 11.0.4

        2.0 - 26 June 2017

        • Upgrade to Firebase 10.2.6
        • Min Android SDK is 14 (4.0.1)

        1.0 - 26 June 2017

        • Initial release with Firebase 10.0.1
        • Min Android SDK is 9 (2.3)
        • Required Accengage SDK 3.6.0

         

        Plugin installation

        Minimum required SDK version: 3.6.0

        JCenter link: https://bintray.com/accengage/maven/plugin-firebase-messaging

        To get our last version of our Firebase plugin, just add this dependency in your build.gradle:

         

        Check plugin installation

        In order to know if the plugin works and is used by the SDK, please activate the SDK logs and look for the following line:


        Integration

        Please check FCM Notifications Setup.

        Plugin - Beacons

        This plugin allows the SDK to:

        • Listen for Beacons
        • Trigger In-Apps and Local Notifications using Beacons

        Changelog

        1.3.0 - 07 Mai 2018

        • Now requires Accengage SDK 3.7.0

        1.2.1 - 13 December 2017

        • Upgrade to required Accengage SDK 3.6.4
        • Target Android API 27

        1.2.0 - 11 September 2017

        • Fixed crash on few constructors overlays when Bluetooth is not available
        • Fixed crash when Bluetooth is disabled during scanning

        1.1.0 - 26 June 2017

        • Manage new SDK 3.6.0 new features
        • Upgrade to required Accengage SDK 3.6.0

        1.0.4 - 14 April 2016

        • Manage new SDK 3.4.0 new features

        1.0.3 - 28 January 2016

        • Replace the Jar with an Aar available on JCenter for an easier integration and a better dependencies management

        1.0.2 - 13 January 2016

        • Fixed some cases where other apps can't properly BIND to an already launched BeaconService

        1.0.1 - 13 October 2015

        • Fixed a rare crash

        1.0.0 - 7 September 2015

        • Initial release of the plugin

        Plugin installation

        Minimum Required SDK Version: 3.6.0

        JCenter link: https://bintray.com/accengage/maven/A4SSDK-Plugin-Beacons

        To get our last version of our Beacons plugin, just add this dependency in your build.gradle:

        If your application has a min-sdk prior to 18, you will have this error:

        You can safely add this line in your AndroidManifest.xml (inside <manifest> tag) to force the compilation:


        Check plugin installation

        In order to know if the plugin works and is used by the SDK, please activate the SDK logs and look for the following line:

        Beacon Integration

        Please check: Beacons - old

        Plugin - Amazon

        This plugin allows the SDK to receive Amazon (ADM) Notifications.

        Changelog

        1.1.0 - 07 Mai 2018

        • Now requires Accengage SDK 3.7.0

        1.0.2 - 13 December 2017

        • Target Android 27

        1.0.1 - 26 June 2017

        • Target Android 25

        1.0.0 - 20 January 2016

        • Initial release

        Plugin installation

        Minimum Required SDK Version: 3.2.0

        JCenter link: https://bintray.com/accengage/maven/A4SSDK-Plugin-Amazon

        To get our last version of our Amazon plugin, just add this dependency in your build.gradle:


        Check plugin installation

        In order to know if the plugin works and is used by the SDK, please activate the SDK logs and look for the following line:

        Integration

        Please check: ADM Notifications Setup