Push notifications SDK for Android

This page details how to install Ortto’s Android software development kit (SDK) in your app to deliver push notifications to contacts.

The following instructions assume your app is built using Gradle.

Each of the code snippets provided is copyable. Simply hover over the snippet and click the copy icon in the top-right corner.

copy code
Example code snippet showing copy function

These instructions cover the key steps to installing the Ortto Android SDK and configuring your app to handle Ortto’s push notifications:

Once you complete these key steps, you’ll be ready to create and send push campaigns.


There are two prerequisites to installing Ortto’s Android SDK:

  1. Create a new (or use an existing) Firebase project and configure Google Cloud roles and permissions.

  2. Upload the .json file created in your Firebase project to Ortto, so that Ortto’s notifications APIs can access your Firebase data.

Learn about creating the Firebase project and enabling access in Ortto in Firebase cloud messaging setup.


There are three key elements to the SDK installation:

  1. Install and initialize the SDK — enable access to the Maven Central repository, install the SDK, and initialize Firebase Cloud Messaging (FCM) and the SDK.

  2. Deep links — enable deep linking in push notifications.

  3. Authorization — register the contact’s device with Ortto.

Unless otherwise stated, all objects and functions described are to be added to your app’s build.gradle script.

Install and initialize the SDK

  1. The Ortto Android SDK utilizes the Maven Central repository. In your settings.gradle file, add mavenCentral() to your list of repositories.

    pluginManagement {
        repositories {
    dependencyResolutionManagement {
        repositories {
  2. Install Ortto’s Android SDK (android-sdk) in your app-level build.gradle file (e.g. at <your-app>/android/app/build.gradle) by adding to your list of dependencies. Replace <version> with the current version of the SDK, found at: https://github.com/autopilot3/ortto-push-android-sdk/releases

    dependencies {
        // ...
        implementation 'com.ortto.android-sdk:<version>'
  3. You need to initialize FCM and Ortto’s SDK before you can use them.

    To do so, override the onCreate method in your Application class (located similar to /app/src/main/java/<namespace-path>/app.java) as follows:

    public class App extends Application {
        public void onCreate() {
            OrttoConfig config = new OrttoConfig(
                "<Application key>",
                "<Ortto Push API endpoint>",
                //see note below regarding endpoint regions
                true // shouldSkipNonExistingContacts
            Ortto.instance().init(config, app);

    Your <Application key> value can be found in your Ortto account, at Settings  Push notifications  Android notifications  Application key.

    The <Ortto Push API endpoint> value can be found in your Ortto account, at Settings  Push notifications  Android notifications  API endpoint.

    Ortto’s default push API service endpoint is: https://capture-api.autopilotapp.com/.

    Ortto customers who have their instance region set to Australia or Europe will use specific push endpoints relative to the region:

    Learn more about shouldSkipNonExistingContacts under Skip non-existing contacts in the Identify people section.

Enable contacts to access deeplinks in your app via push notifications.

In the /app/src/main/java/<namespace-path>/app.java file, implement the CustomDeeplinkCallback interface and createTaskStackFromPayload method, then register this object as the deep link activity handler Ortto.instance().setDeeplinkHandler(this); in the onCreate() method:

public class App extends Application implements CustomDeeplinkCallback {
    public TaskStackBuilder createTaskStackFromPayload(Context context, String deepLink, PushNotificationPayload payload) {
            Intent intent = new Intent(this.getApplicationContext(), DeepActivity.class);
              | Intent.FLAG_ACTIVITY_CLEAR_TOP
              | Intent.FLAG_ACTIVITY_SINGLE_TOP
      intent.putExtra("link", deepLink);
      intent.putExtra("payload", payload);

      return TaskStackBuilder.create(context)
Implementing CustomDeeplinkCallback is optional if you want to customize the Intent that is passed to the activity associated with the deeplink filter in AndroidManifest.xml

The "link" value is what will be used when creating a push campaign with button that has an Android deeplink destination (at the Content step).

deeplink ui


Authorization is required to register the contact’s device with Ortto and enable push notifications for the device. This is handled by passing a Firebase token to Ortto to recognize a contact on their device.

Authorization is automatically requested when calling Ortto.instance().init(<datasource_id>, <endpoint>) (in the Application subclass described under Install and initialize the SDK) but you can request permissions again if required by calling:


Fetch the current Firebase token (generated when you created the Firebase project) and pass it onto the Ortto identity API using the following method:


This method should be called in an activity where you have identified the contact using identify() so Ortto can register which contact the push notification token is attached to.

Tokens are refreshed in the background automatically by Ortto as long as the contact opens the app. Should you wish to update the contact data yourself, use an identify() call where appropriate:


Identifying contacts is described more under Identify people.

You must call dispatchPushRequest before you can identify people (using identify()). Otherwise, Ortto’s API will not be able to handle the identify request.

Identify people

A contact is considered anonymous when they are not logged in to the app or they cannot be identified using the identify function.

While push notifications can be sent to anonymous contacts, we recommend identifying your contacts so they can be linked to your existing CDP records. This then gives you the opportunity to personalize push notifications based on that contact’s data

The identify method identifies contacts who are subscribed to push and recognizes them when they log in to your app. Once logged in, the contact can receive notifications.

Identifying people is also necessary for tracking events.

The identify method can capture the following contact attributes:

  • firstName,

  • lastName,

  • contactId,

  • email,

  • externalId,

  • phone, and

  • acceptsGDPR.

You must identify contacts by a minimum of 1 of the following attributes:

  • email,

  • phone

  • contactId, or

  • externalId.

Additional attributes are optional.

To identify contacts, create a UserID object:

// Non-Fluent
UserID user = new UserID();
user.email = currentUser.getEmail();
user.firstName = "Annie";
user.lastName = "Bennett";
user.acceptsGdpr = false;


If you prefer a fluent interface, use this option:

// Fluent
UserID user = UserID.make()
        .setName(null, null)


The UserID object:

  • saves the contact’s information on the device and enables tracked events to be associated with the contact, and

  • associates the authorization token with the contact to handle push notifications (using Ortto’s android-sdk).

The contact’s device must be authorized before you can identify them (using identify()). Otherwise, Ortto’s API will not be able to handle the identify request.

The SDK can only identify one contact at a time, and will save the most recently identified contact. For example, if Jane Smith is initially identified, and then the identify function calls John Smith, the SDK will consider John Smith the contact using the app.

Ortto’s SDK caches contact information to be sent in token registrations. If you need to clear this data (such as when a contact logs out of your app), call:


Unidentified users

Unidentified users are people who have allowed push notifications but for whom you do not yet have any identifying information.

You have the option to store an unidentified user as a contact immediately when they provide push permission, and be able to send them push notifications, however the contact will have no identifying information.

Or, you can choose to save the contact’s push permission but only record them as a contact once you receive identifying information, and you won’t be able to send messages to them until their identity is confirmed.

Managing unidentified users is performed in the Ortto app, at Settings  Push notifications  Android notifications  Unidentified users.

Permission prompts

Android push notification permissions are obtained via a specific channel in the notification settings of your app (that a contact can access via the app settings on their device).

To obtain a contact’s Android push notification permission, you need to create an Ortto push notification-specific channel in the notification settings (which will be named as appropriate to your organization, e.g. "Deals and promotions" or "Travel ideas").

If the contact has not yet accepted the Ortto-specific notification permission, Android will prompt the user to accept it. To enable this, call:


When the method is called it will result in a modal requesting permission to send push notifications. The method can be called at a time that is suitable to your app and user experience. We recommend calling this method when you are confident the user will accept the push notification permission request.

Set push permission

We give you more control over a contact’s push notification permissions with the setPermission(Permission) method. Use this method if you want further control around how Ortto understands your contacts' messaging preferences.

Call setPermission(Permission) in the Application subclass (described under Install and initialize the SDK).

// Let the SDK determine if the contact has granted permission (Default)

// The contact has explicitly granted permission

// Opt the contact out of push notifications

These methods will send a contact’s push permission value to Ortto.

Skip non-existing contacts

The OrttoConfig class (described under Install and initialize the SDK) accepts a third parameter named shouldSkipNonExistingContacts which controls whether the Ortto API should ignore all permission requests for contacts it cannot identify.

This value is optional and defaults to false.

// Ignore all requests for contacts that do not exist in your Ortto CDP
OrttoConfig config = new OrttoConfig(

Track actions and events

Delivery events

Push message delivery (receipt) is automatically tracked in the Ortto SDK. Delivery events will be reflected in the Ortto app as a Delivered Push activity associated with a contact.

Click tracking

Within your deep link activity handler, call the Ortto instance trackLinkClick with the link that was inserted into the deep link activity.

This method will send a message to Ortto’s servers with the tracking information and return a LinkUtm object with campaign, medium, source and content attributes you can use for marketing data analysis.

The trackLinkClick accepts two arguments, one with a deeplink string and another OnTrackedListener async callback function.

Ortto.instance().trackLinkClick(bundle.getString("link"), new Ortto.OnTrackedListener() {
    public void onComplete(LinkUtm utm) {

This method will populate the Clicked push activity for a contact, including the deep link URL in the activity attributes.

Ortto setup

If you didn’t already add the .json file to the Android notifications setup in Ortto after configuring your Firebase project, do so now.

In Settings  Push notifications  Android notifications  Setup, upload the Service account .json file. This file is available from your Firebase project.

Firebase needs this file to get the required contact credentials used to register device authorization tokens with the Firebase Cloud Messaging Service.

Once the SDK installation and configuration is complete, and you have have provided the required credentials in the Ortto setup, Ortto will wait until it detects activity from your app before your Android platform can be switched ON. Ortto needs to receive an initial request from your app to enable push permissions for a contact (via the permission prompt or an explicitly set push permission), which confirms that your app is correctly configured and is ready to deliver notifications to subscribers. Once the activity is successfully detected, Ortto sets your Android notifications to ON, and you can select the platform when creating a push campaign.

Action index

The action index is not a requirement of the SDK but can be helpful for testing or tracking where contacts are clicking links in your app.

Ortto passes along the index of the action the user took when interacting with the push notification. This can be retrieved in the deep link handler intent under the key action_index. The index value identifies where on a page the contact clicked, where 0 = left, 1 = center, 2 = right.

protected void onCreate(Bundle savedInstanceState) {
        Intent intent = getIntent();
        Bundle bundle = intent.getExtras();
        Uri data = intent.getData();

        if (bundle.containsKey("action_index")) {
            Integer number = bundle.getInt("action_index");