SDK Integration

Basic and mandatory steps

Android Sample

If you want to see how our SDK is integrated and used in some demo apps, you can check our samples apps.

All our samples are available on Github.com

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

dependencies {
  // ...
  compile 'com.ad4screen.sdk:A4SSDK:3.8.1'
}

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

    public class MainActivity extends AppCompatActivity {
    
      @Override
      protected void onNewIntent(Intent intent) {
          super.onNewIntent(intent);
          A4S.get(this).setIntent(intent);
          // ...
      }
    
      @Override
      protected void onResume() {
          super.onResume();
          A4S.get(this).startActivity(this);
          // ...
      }
    
      @Override
      protected void onPause() {
          super.onPause();
          A4S.get(this).stopActivity(this);
          // ...
      }
    }
  • by inheriting A4SActivity

    Changing the parent class on A4SActivity

    import com.ad4screen.sdk.activities.A4SActivity;
    
    public class MyActivity extends A4SActivity {
      // ...
    }

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

  • A4SExpandableListActivity
  • A4SListActivity
  • A4SPreferenceActivity
  • A4SNativeActivity
  • A4SAccountAuthenticatorActivity

Modify your application class

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

Application class

public class MyApplication extends A4SApplication {

    @Override
    public void onApplicationCreate() {
        // ...
    }

    @Override
    public void onApplicationTerminate() {
        // ...
    }

    @Override
    public void onApplicationLowMemory() {
        // ...
    }

    @Override
    public void onApplicationConfigurationChanged(Configuration newConfig) {
        // ...
    }
}

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

<resources>
    // ...

    <string name="acc_partner_id">YOUR_PARTNER_ID</string>
    <string name="acc_private_key">YOUR_PRIVATE_KEY</string>

    <string name="acc_logging">true</string>
    <string name="acc_no_geoloc">true</string>
</resource>

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.

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 acc_optin_data. In your string ressource file set it to true if you plan to send user opt-in to Accengage :

strings.xml

<string name="acc_optin_data">true</string>

If it is false, we consider that the user opt-in has been retrieved another way.

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 3 states the user can be in : YESNO or UNKNOWN.

source.java

A4S.get(this).setOptinData(this, OptinType.YES);

If it is YES, 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 3 states : YESNO or UNKNOWN

source.java

A4S.get(this).setOptinGeoloc(this, OptinType.YES);

Sample

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

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

<resources>
    // ...

    <string name="acc_logging">true</string>
</resource>

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

strings.xml

<resources>
    // ...

    <string name="acc_logging">true,no-toast</string>
</resource>

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 supports 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:

Option Resource name suffix Description

Name

*_name Name of the channel, string
Description *_desc Description 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 name Resource name prefix
General Information acc_channel_general
Service Messages acc_channel_service
News Messages acc_channel_news
Urgent Messages acc_channel_high
Low priority Messages acc_channel_low
Minimum priority Messages acc_channel_min

For exemple, our configuration of the General Information channel:

strings.xml

<!-- Channel : acc_general -->
<string name="acc_channel_general_name">General Information</string>
<string name="acc_channel_general_desc"></string>
<!-- MIN(1), LOW(2), DEFAULT(3), HIGH(4) -->
<string name="acc_channel_general_importance">3</string>
<string name="acc_channel_general_led">true</string>
<string name="acc_channel_general_led_color">#ffffff</string>
<string name="acc_channel_general_vibration">true</string>
<!-- VISIBILITY_SECRET(-1), VISIBILITY_PRIVATE(0), VISIBILITY_PUBLIC(1) -->
<string name="acc_channel_general_lockscreen_visibility">1</string>
<!-- default, none, resource name -->
<string name="acc_channel_general_sound">default</string>
<string name="acc_channel_general_bypass_dnd">false</string>
<string name="acc_channel_general_badge">true</string>

Updating the SDK version


Migrate an existing application using Accengage SDK 3.6.x to the SDK 3.8.x :

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 ac\optin_data_ in your string resource file set it to true if you plan to send user opt-in to Accengage :

strings.xml

<string name="acc_optin_data">true</string>

If it is false, we consider that the user opt-in has been retrieved another way.

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 3 states the user can be in : YES, NO or UNKNOWN.

source.java

A4S.get(this).setOptinData(this, OptinType.YES);

If it is YES, 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 3 states : YES, NO or UNKNOWN

source.java

A4S.get(this).setOptinGeoloc(this, OptinType.YES);

Sample

To see it in action, a sample is available on Github : https://github.com/Accengage/accengage-android-sdk-samples/tree/master/AccGDPR


Migrate an existing application using Accengage SDK 3.6.x to the SDK 3.7.x :

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 acc\optin_data_ in your string resource file set it to true if you plan to send user opt-in to Accengage :

strings.xml

<string name="acc_optin_data">true</string>

If it is false, we consider that the user opt-in has been retrieved another way.

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 3 states the user can be in : YES, NO or UNKNOWN.

source.java

A4S.get(this).setOptinData(this, OptinType.YES);

If it is YES, 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 3 states : YES, NO or UNKNOWN

source.java

A4S.get(this).setOptinGeoloc(this, OptinType.YES);

Sample

To see it in action, a sample is available on Github : https://github.com/Accengage/accengage-android-sdk-samples/tree/master/AccGDPR

Kotlin dependences

build.gradle (project)

buildscript {
    ext.kotlin_version = '1.2.30'

    // ...
    dependencies {
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
    }
}

build.gradle (app)

apply plugin: 'kotlin-android'
// ...

dependencies {
    // ...
    implementation 'com.ad4screen.sdk:A4SSDK:3.7.2'

    implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk7:$kotlin_version"
    implementation "org.jetbrains.kotlin:kotlin-reflect:$kotlin_version"
}

Migrate an existing application using Accengage SDK 3.5.x (or earlier) to the SDK 3.6.x

SDK migration

AndroidManifest.xml

You need to remove the A4SService and all meta datas inside it from your application AndroidManifest.xml. This section is already defined for you in AndroidManifest.xml of the SDK.  

AndroidManifest.xml

-<service
-    android:name="com.ad4screen.sdk.A4SService"
-    android:label="A4S Service"
-    android:process=":A4SService" >
-    <meta-data
-        android:name="com.ad4screen.partnerid"
-        android:value="my-partner-id" />
-    <meta-data
-        android:name="com.ad4screen.privatekey"
-        android:value="my-private-key" />
-</service>

Strings.xml

Now the SDK configuration parameters (partnerId, privateKey, senderId, etc...) are located in the strings.xml file. So you need to move them from AndroidManifest.xml to strings.xml 

strings.xml

<resources>
    // ...

    <string name="acc_partner_id">YOUR_PARTNER_ID</string>
    <string name="acc_private_key">YOUR_PRIVATE_KEY</string>
    <!-- Mandatory to fix an internal bug of 3.6.0 SDK -->
    <string name="acc_unsecure_push">false</string>

    <string name="acc_logging">true</string>
    <string name="acc_no_geoloc">true</string>
</resource>

In the table presented below you can find string names of SDK parameters:

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

Inbox

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

Plugins migration

Beacons

The new version of Accengage SDK 3.6.x is not compatible with the older version of Accengage Beacon Plugin 1.0.x plugin version. You need to upgrade the plugin to the version 1.1.0 or higher:

build.gradle

compile 'com.ad4screen.sdk:A4SSDK-Plugin-Beacons:1.2.0'

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:

android {
    ...

    defaultConfig {
        ...
        minSdkVersion 9
        ...
    }

    ...
}

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:

<!-- [A4S-Geofencing[ -->
<service
    android:name="com.ad4screen.sdk.A4SGeofencingService"
    android:exported="false" />

<receiver android:name="com.ad4screen.sdk.A4SLocationReceiver" android:process=":A4SService">
    <intent-filter>
        <action android:name="android.location.PROVIDERS_CHANGED" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</receiver>
<!-- ]] -->

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:

  • comad4screensdklogo -> comad4screensdknotification_logo
  • comad4screensdktitle -> comad4screensdknotification_title
  • comad4screensdkbody -> comad4screensdknotification_body
  • comad4screensdkpicture -> comad4screensdknotificationbigpicture

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:

android {
  defaultConfig {
    applicationId "com.your.application"
    ...
  }
}

Using GCM Push Notifications

Remove the following lines from your AndroidManifest.xml:

<permission android:name="${applicationId}.permission.C2D_MESSAGE" android:protectionLevel="signature" />

<uses-permission android:name="${applicationId}.permission.C2D_MESSAGE" />
<uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" />

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:

compile 'com.ad4screen.sdk:A4SSDK-Plugin-GooglePlayServices:2.0.0'

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:

compile 'com.ad4screen.sdk:A4SSDK-Plugin-Beacons:1.0.4'

Using Geofences

Add the following lines in your AndroidManifest.xml file:

<receiver android:name="com.ad4screen.sdk.A4SLocationReceiver" android:process=":A4SService">
    <intent-filter>
        <action android:name="android.location.PROVIDERS_CHANGED" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</receiver>

Send a basic push

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:

Android Monitor

A4S|INFO|A4S SDK VERSION : Ax.y.z (Build : 123abc456def789hij)
A4S|ERROR|***********************************/!\***********************************
A4S|ERROR|/!\ Logging is Enabled and must be DISABLED in production environment /!\
A4S|ERROR|***********************************/!\***********************************
A4S|INFO|ManifestChecker|Manifest configuration seems to be OK