Getting Started

Requirements

Login Information

You'll 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

Cloud Messaging

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

Cloud Messaging solution
Accengage Plugin
Dependecy
FCM plugin-firebase-messaging firebase-messaging:17.0.0
ADM A4SSDK-Plugin-Amazon amazon-device-messaging-1.0.2

GCM

GCM is deprecated from April 11, 2019 in favor of Firebase.

Please follow this documentation to migrate your project.

plugin-play-services-push

play-services-gcm:15.0.1

Check out our pages to get started with:

Activate push notifications

FCM (Firebase Cloud Messaging)

FCM is the new version of GCM. For this reason it's recommended to use plugin-firebase-messaging plugin instead of plugin-play-services-push.

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 or import your GCM project if you are migrating from GCM to FCM. 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 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.

If you have already added FCM to your project please check that the version of firebase-messaging library is 17.0.0 to avoid conflicts with the version that Accengage plugin-firebase-messaging plugin uses.

app-level build.gradle

dependencies {
    // ...
    compile 'com.google.firebase:firebase-messaging:17.0.0'
}

apply plugin: 'com.google.gms.google-services'

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 Accengage SDK and plugin-firebase-messaging 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:4.0.4'
}

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

app-level build.gradle

dependencies {
    // ...
    compile 'com.ad4screen.sdk:A4SSDK:4.0.4'
    compile 'com.ad4screen.sdk:plugin-firebase-messaging:4.0.4'
}

The plugin depends on the firebase-messaging:19.0.0 library, so you don't need to add it by yourself.

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.

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 you 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>

</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.

Sample

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

GCM (Google Cloud Messaging)

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.

Add sender ID to your app

The last thing you need to do is to add your sender ID to strings.xml as shown on the code snippet presented below.

strings.xml

<resources>
    // ...
    <string name="acc_sender_id">gcm:your_sender_id</string>
</resource>

You can find more information about the sender IDs on this page.

Multiple push providers

If you have another push system integrated into your app that is using GCM too, here is how to proceed in order to get them working as well:

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

MyGCMHandler.java

public class MyGCMHandler extends GCMHandler {

    @Override
    protected void onPushReceive(Context context, Intent intent) {
        super.onPushReceive(context, intent);
        //Do things and call other push systems receiver
    }
}

OnPushReceive will ONLY be called for push notifications that do not come from our Web Interface.

Finally, declare your receiver inside AndroidManifest.xml:

AndroidManifest.xml

<receiver android:name=".MyGCMHandler"
          android:permission="com.google.android.c2dm.permission.SEND" >

<intent-filter>
    <action android:name="com.google.android.c2dm.intent.RECEIVE" />
    <action android:name="com.google.android.c2dm.intent.REGISTRATION" />
    <category android:name="your-package" />
</intent-filter>

</receiver>

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

ADM (Amazon Device Messaging)

To implement ADM (Amazon Device Messaging) you need to use A4SSDK-Plugin-Amazon.

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.

Configure the Accengage dashboard for push notifications

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.

Configure GCM with Accengage User Interface

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
  6. Go to Accengage User Interface, and to Settings > Manage Application and find your application
  7. 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 your senderID in the A4SService <service> tag:

<meta-data android:name="com.ad4screen.senderid" android:value="gcm:yoursenderid" />

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

Adding required permissions

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

<receiver android:name="com.ad4screen.sdk.GCMHandler"
          android:permission="com.google.android.c2dm.permission.SEND" >

<intent-filter>
    <action android:name="com.google.android.c2dm.intent.RECEIVE" />
    <action android:name="com.google.android.c2dm.intent.REGISTRATION" />
    <category android:name="your-package" />
</intent-filter>

</receiver>

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

Manual GCM Registration

If you do not want 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:

A4S.get(context).sendPushToken("your_token");

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

Configure ADM with Accengage User Interface

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.

  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.

Configure URL Schemes

Deep links are URLs that take users directly to specific content in your app. These URLs are used by Accengage dashboard to specify Push actions and InApp actions. Check out this Android page to get to know more about creating deep links. You may also find this Codelab useful.

Here is an example of declaring two URL schemes testapp://p1 and testapp://p2 in your app

AndroidManifest.xml

<application
    android:allowBackup="true"
    android:icon="@drawable/ic_launcher"
    android:label="@string/app_name"
    android:theme="@style/AppTheme" >
    <activity
        android:name="MainActivity"
        android:label="@string/app_name" >
        <intent-filter>
            <action android:name="android.intent.action.MAIN" />
            <category android:name="android.intent.category.LAUNCHER" />
        </intent-filter>
        <!-- we are declaring schema testapp://p1 for this activity -->
        <intent-filter>
            <action android:name="android.intent.action.VIEW" />
            <category android:name="android.intent.category.DEFAULT" />
            <category android:name="android.intent.category.BROWSABLE" />
            <data android:scheme="testapp" android:host="p1" />
        </intent-filter>
    </activity>
    <activity
        android:name="SecondActivity">
        <!— This activity is launched by scheme url testapp://p2 -->
        <intent-filter>
            <action android:name="android.intent.action.VIEW" />
            <category android:name="android.intent.category.DEFAULT" />
            <category android:name="android.intent.category.BROWSABLE" />
            <data android:scheme="testapp" android:host="p2" />
        </intent-filter>
    </activity>
</application>

If you want, you can retrieve data (custom parameters, for instance) from URL scheme using the code below:

@Override
protected void onResume() {
    super.onResume();
    Intent intent = getIntent();
    if (intent != null && intent.getData() != null) {
        Uri uri = intent.getData(); // parse uri for parameters and display specific data
    }
}