HomeGuidesAPI Reference
Submit Documentation FeedbackJoin Developer CommunityOptimizely GitHubOptimizely NuGetLog In

Android integration

This topic describes how to integrate your Android app for receiving push messages via Optimizely Campaign.

This topic includes access to the Software Developer Kit (SDK) and documentation to receive required code components for integration into your app.


See Mobile Push how to set up required mobile push components before you start developing.

System requirements

  • Android Version 4.1 or higher.
  • Android API Level 16 or higher.
  • Google Play Store Version 7.5 or higher.

Registering with Firebase Cloud Messaging (FCM)

  1. Open the Firebase console and log in using your Google account.
  2. Click Add project and create a new project for the app.
  3. Click Settings and then Project settings.
  4. Open the Cloud Messaging tab and note the Legacy server key and sender ID for passing to Optimizely Campaign.
  5. Click Settings and then Users and permissions.
  6. In the navigation on the left-hand side, click Service accounts.
  7. At the top of the navigation, click + CREATE SERVICE ACCOUNT.
  8. Enter the name of the service account and provide an optional service account ID.
  9. Select Furnish a new private key and activate the JSON option.
  10. Click Create and save the generated JSON file. The new service account appears in the overview along with the key ID.

Downloading SDK

Integrating Android SDK

  1. Include the SDK-JAR and Google Play Service. If you use the Gradle build system, enter the dependencies as below into your build.gradlefiles.
    1. Enter the following into the top level project build.gradle file:
                classpath 'com.android.tools.build:gradle:3.1.4'
                classpath 'com.google.gms:google-services:4.1.0'
  1. In the lower level build.gradle of your app, define the dependencies for episerver-push-android-sdk.jar. In this example the file resides in the libs directory. In addition you add dependencies for firebase-core and firebase-messaging:
                api fileTree(dir: '../libs', include: ['*.jar'])
                api 'com.google.firebase:firebase-core:16.0.3'
                api 'com.google.firebase:firebase-messaging:17.3.1'
  1. Add your message notification logo as Drawable with the name bm_default_notification_icon.



Always create an icon to set your messages apart. To help designing a product icon, see Material Design.

  1. Create a class that inherits from com.episerver.sdk.PushNotificationReceiver. You can override the methods onNotificationClicked(Context, PushMessage) and onNotificationReceived(Context, PushMessage) to handle incoming notifications.

Notifications received while your app is in the background are sent to the system tray by the Android system. When the recipient clicks the notification it can be handled in the onNotificationClicked method.

Notifications received while the app is in the foreground are not shown as a notification automatically. They can be handled in the onNotificationReceived method where you can update your app or show a custom notification to the recipient. The data transferred via the push message are available in the PushMessage object.

Optionally, you can call the method com.episerver.sdk.EpiSdk.trackOpen(Context, PushMessage) from within the handleClick method to track clicks on messages.

  1. Register the class that inherits from PushNotificationReceiver in the AndroidManifest, and change the class names accordingly:
<receiver android:name=".DemoPushNotificationReceiver"
                  android:exported="true" >
            <action android:name="[com.example].NOTIFICATION_CLICKED" />
            <action android:name="[com.example].NOTIFICATION_RECEIVED" />
Replace [com.example] with the package name of your app.
  1. Register the following services in the AndroidManifest:
<service android:name="com.episerver.sdk.EpiMessagingService">
            <action android:name="com.google.firebase.MESSAGING_EVENT" />
        <service android:name="com.episerver.sdk.RestApiService"
                 android:exported="false" >
        <service android:name="com.episerver.sdk.TrackingUrlService"
                 android:exported="false" >
  1. Register the following Activity in the AndroidManifest:
<activity android:name="com.episerver.sdk.PushNotificationClickedActivity"
                  android:exported="true" >
            <action android:name="[com.example].intent.action.PUSH_NOTIFICATION" />
            <category android:name="android.intent.category.DEFAULT" />

Replace [com.example] with the package name of your app.

  1. When starting the application, or when the recipient logs in or goes online, the SDK must be initialized to receive messages. Initialization of the framework:
          getApplicationContext(),        // App context
          "xxx");                         // Optimizely provides the auth token to authenticate calls.

Alternatively, for recipient lists with a recipient ID field which is not the standard GCM recipient token:

          getApplicationContext(),       // App context
          "xxx",                         // Optimizely provides the auth token to authenticate calls.
          recipientId);                  // ID of the app user​

What’s Next