Android SDK

You can integrate the Outbound Android SDK in your Android app to send user and event data to Outbound from the user's device. You can also use it to manage push notification tokens and perform other tasks.

The SDK supports Google Cloud Messaging (GCM) and Firebase Cloud Messaging (FCM) for push notifications.

This document covers the following topics:

See also the Outbound SDK Javadoc.

Install the Outbound SDK

  1. Add the Outbound repository in your project:

    allprojects {
      repositories {
        maven {
          url  "http://dl.bintray.com/outbound/maven"
        }
      }
    }
    
  2. Add the following dependency in your Gradle file:

    compile 'io.outbound.sdk:android-sdk:0.4.0'
    

    For the latest version, see the SDK source code on Github.

  3. (GCM apps only) Add the following GCM permissions to your AndroidManifest.xml file:

    <permission
      android:name="YOUR_PACKAGE_NAME.gcm.permission.C2D_MESSAGE"
      android:protectionLevel="signature" />
    <uses-permission
      android:name="YOUR_PACKAGE_NAME.gcm.permission.C2D_MESSAGE" />
    

    Replace YOUR_PACKAGE_NAME with your app's package name.

    Also register the GCM message receiver in the AndroidManifest.xml file:

    <receiver
      android:name="io.outbound.sdk.OutboundPushReceiver"
      android:permission="com.google.android.c2dm.permission.SEND" >
      <intent-filter>
        <action android:name="com.google.android.c2dm.intent.RECEIVE" />
      </intent-filter>
    </receiver>
    
  4. (FCM apps only) Add the following FCM permissions to your AndroidManifest.xml file:

    <service android:name="io.outbound.sdk.OutboundMessagingService">
      <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT"/>
      </intent-filter>
    </service>
    
  5. Register service to handle opening your app from push notifications in your AndroidManifest.xml file:

    <service
      android:name="io.outbound.sdk.OutboundService"
      android:exported="false"
      android:label="OutboundService" >
      <intent-filter>
        <action android:name="YOUR_PACKAGE_NAME.outbound.action.OPEN_NOTIF" />
      </intent-filter>
    </service>
    

    Replace YOUR_PACKAGE_NAME with your app's package name.

    You can extend OutboundPushReceiver, OutboundMessagingService, and OutboundService with your own implementations. See the Outbound SDK Javadoc for each class on Github.

  6. (FCM apps only) Include the google-services.json file at the root level of your app. For more information, see Google Services Gradle Plugin in the Google docs.

  7. In the onCreate method of your application class, initialize the Outbound SDK with your Outbound private API key, Google Cloud Project ID number, and your notification channel ID:

    Outbound.init(this, OUTBOUND_PRIVATE_KEY, GOOGLE_PROJECT_ID, OUTBOUND_CHANNEL_ID);
    

    For more information on the private key, see Authentication in the introduction.

    The notification channel must be created before Outbound is initalized and is required for Android versions greater than 8.0 (Oreo).

    Here is an example of how to override the onCreate method:

    private static final String OUTBOUND_CHANNEL_ID = "io.outbound.example.notifications";
    
    @Override public void onCreate() {
        super.onCreate();
    
        if (android.os.Build.VERSION.SDK_INT >= android.os.Build.VERSION_CODES.O) {
            int importance = NotificationManager.IMPORTANCE_DEFAULT;
            NotificationChannel notificationChannel = new NotificationChannel(notificationChannelId, "Outbound Notifications", importance);
            notificationChannel.enableVibration(true);
    
            NotificationManager notificationManager = (NotificationManager) getSystemService(Context.NOTIFICATION_SERVICE);
            notificationManager.createNotificationChannel(notificationChannel);
        }
    
        Outbound.init(this, OUTBOUND_PRIVATE_KEY, GOOGLE_PROJECT_ID, OUTBOUND_CHANNEL_ID);
    }
    

    More information about how to create Android notification channels can be found in the official Android documentation.

  8. Add the following lines to your ProGuard file:

    -keep class io.outbound.sdk.User { *; }
    -keep class io.outbound.sdk.Event { *; }
    

Identify a user

Use the identify() method to send user data to Outbound. The method takes the following argument:

  • a User object containing the user attributes

See identify() in the Outbound SDK Javadoc.

Example
User user = new User.Builder()
           .setFirstName("John")
           .setLastName("Doe")
           .setEmail("john@domain.com")
           .setPhoneNumber("415-555-1234")
           .build();
Outbound.identify(user);

For more information about the user attributes, see Users.

Track an event

Use the track() method to send event data to Outbound. The method takes the following argument:

  • an Event object containing the event name and properties

See track() in the Outbound SDK Javadoc.

Example
Map<String, Object> properties;
Event event = new Event("event_name", properties);
Outbound.track(event);

For more information, see:

Enable deep linking

To use the deep-linking capabilities in Outbound push notifications, you must set up your app to handle links. To do so, add an <intent-filter> to each of your activities you want to be linkable. For more information, see Add Intent Filters for Your Deep Links in the Android Developers documentation.

To enable Google to crawl your app content and allow users to enter your app from search results, you must add intent filters for the relevant activities in your app manifest. These intent filters allow deep linking to the content in any of your activities.

Log out user

You can use use the logout() method to make Outbound "forget" a user when the user logs out of your app:

Outbound.logout();

This clears the user data from the cache. It doesn't disable the user's GCM device token with Outbound.

See logout() in the Outbound SDK Javadoc.

Disable a device token

Use the disable() method if you no longer want to send push notifications to the user's device.

Outbound.disable();

See disable() in the Outbound SDK Javadoc.

Adding custom notification sounds and icons

The team in your organization responsible for creating Outbound campaigns can specify the sound to play when a notification arrives. The options are: silent, default, and custom. Before the campaign team can select the custom sound, a developer must place the sound file in the project's resources (res) folder.

Similarly, the campaign team can specify a small and large icon to display with the notifications. Example:

image

A developer must also place the image files in the project's resources (res) folder.

In both cases, you as the developer must forward the resource path to the campaign team in your organization. Leave out the file extension. The campaign team must enter the path manually in the campaign UI.

Note: This feature is only available in the SDK version 0.2.0 or later.