Skip to content

SDK Reference

Android Native SDK

Kontext ANDROID Native API Reference

Just starting with Android?

Check out our Android SDK Setup guide.

Upgrade to 3.5.1+

A number the methods and classes below were recently added in our 3.5.1 SDK. Make sure you have updated to this version.

Calls Type Description
Privacy
setRequiresUserPrivacyConsent Method Delays initialization of the SDK until the user provides privacy consent
provideUserConsent Method Tells the SDK that the user has provided privacy consent (if required)
userProvidedPrivacyConsent Method Returns a boolean indicating if the SDK is waiting for user privacy consent
Stauts
getPermissionSubscriptionState Method Current Permission and Subscription status
addPermissionObserver Method Permission status changes
addSubscriptionObserver Method Subscription status changes
Events
sendEvent Method Send a single user event to Kontext
sendEvents Method Batch and send multiple events to Kontext
sendScreen Method Send screen view activity to Kontext
setUserProfile Method Send user properties to Kontext
Data
promptLocation Method Prompt Users for Location
Receiving Notifications
postNotification Method Send or schedule a notification to a user
cancelNotification Method Delete a single app notification
clearKontextNotifications Method Delete all app notifications
setSubscription Method Opt users in or out of receiving notifications
NotificationExtenderService Method + Manifest Add custom data to a notification, or override notification options
Notification Events
NotificationReceivedHandler Handler When a notification is received by a device
NotificationOpenedHandler Handler When a user takes an action on a notification
Opened Action Android Manifes Disable resuming launcher activity when notification is opened
Objects
OSNotificationOpenResult Object Information returned from a notification the user received
OSNotification Object Notification the user received
OSNotificationAction Action the user took on the notification
OSNotificationPayload Contents and settings of the notification the user received
Appearance
setInFocusDisplaying Method Change how the notification is displayed when your app is actively being used.
enableVibrate Method When user receives notification, vibrate device less
enableSound Method When user receives notification, do not play a sound
Debug
setDebugLevel Method Enable logging to help debug Kontext implementation

Privacy

setRequiresUserPrivacyConsent

METHOD

Lets your app require the user's privacy consent before it will initialize. If you call this method and pass in true, the SDK will delay initialization until your application calls `provideUserConsent(true).

If the SDK is waiting for the user's consent, calling any Kontext SDK methods will do nothing but print a warning. The user will not be registered for push notifications until this happens.

1
2
// the SDK will delay initialization and won't collect data.
Kontext.setRequiresUserPrivacyConsent(true);

provideUserConsent

If your application is set to require the user's privacy consent, you can provide this consent using this method. Until you call provideUserConsent(true), the SDK will not fully initialize and will not send any data to Kontext.

1
2
3
4
public void onUserTappedProvidePrivacyConsent(View v) {
  //will initialize the Kontext SDK and enable push notifications
  Kontext.provideUserConsent(true);
}

userProvidedPrivacyConsent

METHOD

Returns a boolean indicating if the user has provided privacy consent.

disableGmsMissingPrompt

BUILDER METHOD

Prompts the user to update/enable Google Play services if it's disabled on the device.

Parameter Type Description
prompt boolean false (DEFAULT) - prompt users
true to never show the out of date prompt.
1
2
3
Kontext.startInit(this)
  .disableGmsMissingPrompt(true)
  .init();

unsubscribeWhenNotificationsAreDisabled

BUILDER METHOD

If notifications are disabled for your app, unsubscribe the user from Kontext. This will happen when your users go to Settings > Apps and turn off notifications, or if they long press one of your notifications and select "block notifications". This is false by default.

Parameter Type Description
prompt boolean false (DEFAULT) - prompt users
true to never show the out of date prompt.
1
2
3
Kontext.startInit(this)
  .disableGmsMissingPrompt(true)
  .init();

unsubscribeWhenNotificationsAreDisabled

BUILDER METHOD

If notifications are disabled for your app, unsubscribe the user from Kontext. This will happen when your users go to Settings > Apps and turn off notifications, or if they long press one of your notifications and select "block notifications". This is false by default.

Parameter Type Description
prompt boolean false (DEFAULT) - don't unsubscribe users
true - unsubscribe users when notifications are disabled
1
2
3
Kontext.startInit(this)
  .unsubscribeWhenNotificationsAreDisabled(true)
  .init();

Status methods

The following methods provide details on the permission and subscribed state of the device. Use getPermissionSubscriptionState to get the current immediate state and use addPermissionObserver and / or addSubscriptionObserver to react to changes.

Status Recommendations

getPermissionSubscriptionState - Use to load your UI to the correct state. Such as showing a toggle button to enable notifications.

addSubscriptionObserver - Use to update your server when the user becomes subscribed or unsubscribed and to get the Kontext player / user id. Example if you need to store the Kontext player / user id on your backend you can make a REST API call directly from the observer's callback. The Kontext observer ONLY fires when there is a change, including NOT firing even if the app has been restarted. This helps ensure your not making unnecessary network calls to your backend on each app restart if nothing changed.

getPermissionSubscriptionState

METHOD

Get the current notification and permission state. Returns a OSPermissionSubscriptionState type described below.

Parameter Type Description
getPermissionStatus() OSPermissionState Android Notification Permissions state
getSubscriptionStatus() OSSubscriptionState Google and Kontext subscription state
1
2
3
4
5
6
7
OSPermissionSubscriptionState status = Kontext.getPermissionSubscriptionState();
status.getPermissionStatus().getEnabled();

status.getSubscriptionStatus().getSubscribed();
status.getSubscriptionStatus().getUserSubscriptionSetting();
status.getSubscriptionStatus().getUserId();
status.getSubscriptionStatus().getPushToken();

OSPermissionState

CLASS

The Notification permission status of your app. Contains enabled value to know if the user has turned off notifications for your app.

Parameter Type Description
getEnabled() boolean true if notifications are enabled.
Will only be false if the user disables notifications for your app from the system settings

OSSubscriptionState

CLASS

Provides subscription state details of subscribed to push as well as the Kontext player / user id and the devices push token.

Parameter Type Description
getSubscribed() boolean true if the device can receive push notifications from Kontext.
false if the device has disabled push notifications or not successfully registered yet with either Kontext or FCM with a valid push token.
getUserId() String The Kontext player / user id for the device. null if the device hasn't registered with Kontext's server yet.
getPushToken() String The GCM / FCM push token for the device. null if the device hasn't registered with Google's server yet.

addPermissionObserver

HANDLER

The onOSPermissionChanged method will be fired on the passed-in object when a notification permission setting changes. This happens when the user enables or disables notifications for your app from the system settings outside of your app. Disable detection is supported on Android 4.4+.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
public class MainActivity extends Activity implements OSPermissionObserver {
  protected void onCreate(Bundle savedInstanceState) {
    Kontext.addPermissionObserver(this);
  }

  public void onOSPermissionChanged(OSPermissionStateChanges stateChanges) {
    if (stateChanges.getFrom().getEnabled() &&
        !stateChanges.getTo().getEnabled()) {
         new AlertDialog.Builder(this)
             .setMessage("Notifications Disabled!")
             .show();
      }

      Log.i("Debug", "onOSPermissionChanged: " + stateChanges);
  }
}

// Example Logcat entry - User disabling notifications then returning to your app.
// onOSPermissionChanged{"from":{"enabled":true},"to":{"enabled":false}}

Keep a Reference

Make sure to hold a reference to your observable at the class level, otherwise it my not fire.

Leak Safe

Kontext holds a weak reference to your observer so it's guaranteed not to leak your Activity.

OSPermissionStateChanges

CLASS

Instance is given to your onOSPermissionChanged method which provides what the value was ("from") and what the value is now ("to").

Parameter Type Description
getFrom() OSSubscriptionState What the state was
getTo() OSSubscriptionState What the state is now

addSubscriptionObserver

METHOD

The onOSSubscriptionChanged method will be fired on the passed-in object when a notification subscription property changes.

This includes the following events:

  • Getting a Registration Id (push token) from Google
  • Getting a player / user id from Kontext
  • Kontext.setSubscription is called
  • User disables or enables notifications
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
public class MainActivity extends Activity implements OSSubscriptionObserver {
  protected void onCreate(Bundle savedInstanceState) {
    Kontext.addSubscriptionObserver(this);
  }

  public void onOSSubscriptionChanged(OSSubscriptionStateChanges stateChanges) {
    if (!stateChanges.getFrom().getSubscribed() &&
        stateChanges.getTo().getSubscribed()) {
         new AlertDialog.Builder(this)
             .setMessage("You've successfully subscribed to push notifications!")
             .show();
        // get player ID
        stateChanges.getTo().getUserId();
      }

      Log.i("Debug", "onOSPermissionChanged: " + stateChanges);
  }
}

/*
Example Logcat entry - User disabling notifications then returning to your app.
onOSSubscriptionChanged:
{"from":{"pushToken":"APA91bG9cmZ262s5gJhr8jvbg1q7aiviEC6lcOCgAQliEzHKO3eOdX5cm7IQqMSWfy8Od7Ol3jSjFfvCfeO2UYUpanJCURJ8RdhgEuV8grYxOCwPNJr5GoqcWTQOaL9u-qE2PQcFlv4K","userSubscriptionSetting":true,"subscribed":false},
 "to":  {"userId":"22712a53-9b5c-4eab-a828-f18f81167fef","pushToken":"APA91bG9cmZ262s5gJhr8jvbg1q7aiviEC6lcOCgAQliEzHKO3eOdX5cm7IQqMSWfy8Od7Ol3jSjFfvCfeO2UYUpanJCURJ8RdhgEuV8grYxOCwPNJr5GoqcWTQOaL9u-qE2PQcFlv4K","userSubscriptionSetting":true,"subscribed":true}}

Keep a Reference

Make sure to hold a reference to your observable at the class level, otherwise it my not fire.

Leak Safe

Kontext holds a weak reference to your observer so it's guaranteed not to leak your Activity.

OSSubscriptionStateChanges

CLASS

Instance is given to your onOSSubscriptionChanged method which provides what the value was ("from") and what the value is now ("to").

Parameter Type Description
getFrom() OSPermissionState What the state was (past)
getTo() OSPermissionState What the state is now

Events

sendEvent

METHOD

Tag a user based on an app event of your choosing so later you can create segments in Segments to target these users. Use sendTags if you need to set more than one tag on a user at a time.

Parameter Type Description
key String Key of your choosing to create or update.
value String Value to set on the key.
1
2
3
JSONObject payload = new JSONObject();
      payload.put("Product Added", "Applie iPhone");
      Kontext.sendEvent("Product", payload);

sendEvents

METHOD

Tag a user based on an app event of your choosing so later you can create segments in Segments to target these users.

Parameter Type Description
keyValues JSONObject Key value pairs of your choosing to create or update.
1
2
3
4
JSONObject events = new JSONObject();
    events.put("key1", "value1");
    eventss.put("key2", "value2");
    Kontext.sendEvents(events);

sendScreen

METHOD

Tag a user based on an screen view event of your choosing so later you can create segments in Segments to target these users.

Parameter Type Description
keyValues JSONObject Key value pairs of your choosing to create or update.
1
Kontext.sendScreen("screen Name");      // String

setUserProfile

METHOD

Tag a user based on their properties like name, age, gender, location, etc.

Parameter Type Description
keyValues HashMap Key value pairs of your choosing to create or update.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
HashMap<String, Object> profileUpdate = new HashMap<String, Object>();
      profileUpdate.put("Name", "John Dow");                  // String
      profileUpdate.put("Email", "john@gmail.com");               // Email address of the user
      profileUpdate.put("Phone", "+222333444");                 // Phone (with the country code)
      profileUpdate.put("Gender", "M");                           // Can be either M or F
      profileUpdate.put("Employed", "Y");                         // Can be either Y or N
      profileUpdate.put("Education", "Graduate");                 // Can be either Graduate, College or School
      profileUpdate.put("Married", "Y");                          // Can be either Y or N
      profileUpdate.put("DOB", new Date());                       // Date of Birth. Set the Date object to the appropriate value first
      profileUpdate.put("Age", 28);                               // Not required if DOB is set
      profileUpdate.put("Tz", "Asia/Kolkata");                    
      profileUpdate.put("Photo", "www.foobar.com/image.jpeg");    // URL to the Image

      Kontext.setUserProfile(profileUpdate);

Data

promptLocation

METHOD

Prompts the user for location permissions. This allows for geotagging so you can send notifications to users based on location.

1
Kontext.promptLocation();

Make sure you have one of the following permissions in your AndroidManifest.xml as well.

1
2
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>

Notifications

postNotification

METHOD

Allows you to send notifications from user to user or schedule ones in the future to be delivered to the current device.

Parameter Type Description
paramters JSONObject Contains notification options

cancelNotification

METHOD

Cancels a single Kontext notification based on its Android notification integer id. Use instead of Android's NotificationManager.cancel(id); otherwise the notification will be restored when your app is restarted.

1
2
int id = 1234;
Kontext.cancelNotification(id);

clearKontextNotifications

METHOD

Removes all Kontext notifications from the Notification Shade. If you just use NotificationManager.cancelAll();Kontext notifications will be restored your app is restarted.

1
Kontext.clearKontextNotifications();

setSubscription

METHOD

You can call this method with false to opt users out of receiving all notifications through Kontext. You can pass true later to opt users back into notifications.

Parameter Type
enable boolean
1
Kontext.setSubscription(false);

NotificationExtenderService

METHOD

Kontext supports sending additional data along with a notification as key value pairs. You can read this additional data when a notification is opened by adding a NotificationOpenedHandler instead.

However if you want to do one of the following continue with the instructions below.

  • Receive data in the background with or without displaying a notification.
  • Override specific notification settings depending on client side app logic such as custom accent color, vibration pattern, or other any other NotificationCompat options available.

1. Create a class that extents NotificationExtenderService and implement the onNotificationProcessing method.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
import com.kontext.OSNotificationPayload;
import com.kontext.NotificationExtenderService;

public class NotificationExtenderBareBonesExample extends NotificationExtenderService {
   @Override
   protected boolean onNotificationProcessing(OSNotificationReceivedResult receivedResult) {
        // Read properties from result.

      // Return true to stop the notification from displaying.
      return false;
   }
}

2. Add the following to your AndroidManifest.xml. Replace 'YOUR_CLASS_NAME' with the class name you used above.

1
2
3
4
5
6
7
8
<service
   android:name=".YOUR_CLASS_NAME"
   android:permission="android.permission.BIND_JOB_SERVICE"
   android:exported="false">
   <intent-filter>
      <action android:name="com.kontext.NotificationExtender" />
   </intent-filter>
</service>

3. To override or extend specific notification properties call displayNotification with OverrideSettings.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
import android.support.v4.app.NotificationCompat;

import com.kontext.OSNotificationPayload;
import com.kontext.NotificationExtenderService;

import java.math.BigInteger;

public class NotificationExtenderExample extends NotificationExtenderService {
   @Override
   protected boolean onNotificationProcessing(OSNotificationReceivedResult receivedResult) {
      OverrideSettings overrideSettings = new OverrideSettings();
      overrideSettings.extender = new NotificationCompat.Extender() {
         @Override
         public NotificationCompat.Builder extend(NotificationCompat.Builder builder) {
            // Sets the background notification color to Green on Android 5.0+ devices.
            return builder.setColor(new BigInteger("FF00FF00", 16).intValue());
         }
      };

      OSNotificationDisplayedResult displayedResult = displayNotification(overrideSettings);
            Log.d("KontextExample", "Notification displayed with id: " + displayedResult.androidNotificationId);

      return true;
   }
}

Additional Notes NotificationExtenderService is an Android IntentService so please do all your work synchronously. A wake lock is obtained so the device will not sleep while you're processing the payload.

Receiving Notifications

NotificationReceivedHandler

HANDLER

Fires when a notification is received. It will be fired when your app is in focus or in the background.

Parameter Type Description
notification OSNotification Contains user's response and properties of the notification.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
class ExampleNotificationReceivedHandler implements Kontext.NotificationReceivedHandler {
  @Override
  public void notificationReceived(OSNotification notification) {
    JSONObject data = notification.payload.additionalData;
    String customKey;

    if (data != null) {
      customKey = data.optString("customkey", null);
      if (customKey != null)
        Log.i("KontxtExample", "customkey set with value: " + customKey);
    }
  }
}

Important Behavior Note

If you will be displaying your own in app message when a notification is received make sure to call inFocusDisplaying with None to disable Kontext's in app AlertBox.

NotificationOpenedHandler

HANDLER

Use to process a Kontext notification the user just tapped on.

Parameter Type Description
result OSNotificationOpenResult Contains user's response and properties of the notification.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
class ExampleNotificationOpenedHandler implements Kontext.NotificationOpenedHandler {
  // This fires when a notification is opened by tapping on it.
  @Override
  public void notificationOpened(OSNotificationOpenResult result) {
    OSNotificationAction.ActionType actionType = result.action.type;
    JSONObject data = result.notification.payload.additionalData;
    String customKey;

    if (data != null) {
      customKey = data.optString("customkey", null);
      if (customKey != null)
        Log.i("KontextExample", "customkey set with value: " + customKey);
    }

    if (actionType == OSNotificationAction.ActionType.ActionTaken)
      Log.i("KontextExample", "Button pressed with id: " + result.action.actionID);

    // The following can be used to open an Activity of your choice.
    // Replace - getApplicationContext() - with any Android Context.
    // Intent intent = new Intent(getApplicationContext(), YourActivity.class);
    // intent.setFlags(Intent.FLAG_ACTIVITY_REORDER_TO_FRONT | Intent.FLAG_ACTIVITY_NEW_TASK);
    // startActivity(intent);

     // Add the following to your AndroidManifest.xml to prevent the launching of your main Activity
     //   if you are calling startActivity above.
     /* 
        <application ...>
          <meta-data android:name="com.kontext.NotificationOpened.DEFAULT" android:value="DISABLE" />
        </application>
     */
  }
}

OSNotificationOpenResult

CLASS

The information returned from a notification the user received.

Parameter Type Description
notification OSNotification Notification the user received.
action OSNotificationAction The action the user took on the notification.

OSNotification

CLASS

The notification the user received.

Parameter Type Description
isAppInFocus boolean Was app in focus.
shown boolean Was notification shown to the user. Will be false for silent notifications.
androidNotificationId int Android Notification assigned to the notification. Can be used to cancel or replace the notification.
payload OSNotificationPayload Payload received from Kontext.
displayType DisplayType How the notification was displayed to the user. Can be set to NotificationInAppAlert, or None if it was not displayed.
groupedNotifications List Notification is a summary notification for a group this will contain all notification payloads it was created from.

DisplayType

How the notification was displayed to the user. Part of OSNotification. See inFocusDisplaying for more information on how this is used.

Notification - native notification display. InAppAlert (DEFAULT) - native alert dialog display. None - notification is silent, or inFocusDisplaying is disabled.

OSNotificationAction

CLASS

The action the user took on the notification.

Parameter Type Description
type ActionType Was the notification opened normally (Opened) or was a button pressed on the notification (ActionTaken).
actionId String If type == ActionTaken then this will contain the id of the button pressed.

OSNotificationPayload

CLASS

Contents and settings of the notification the user received.

Parameter Type Description
notificationID String Kontext notification UUID.
title String Title of the notification.
body String Body of the notification.
additionalData JSONObject Custom additional data that was sent with the notification.
smallIcon String Small icon resource name set on the notification.
largeIcon String Large icon set on the notification.
bigPicture String Big picture image set on the notification.
smallIconAccentColor String Accent color shown around small notification icon on Android 5+ devices. ARGB format.
launchUrl String URL to open when opening the notification.
sound String Sound resource to play when the notification is shown.
ledColor String Devices that have a notification LED will blink in this color. ARGB format
lockScreenVisibility int Privacy setting for how the notification should be shown on the lockscreen of Android 5+ devices.
1 (DEFAULT) - Public (fully visible)
0 - Private (Contents are hidden)
-1 - Secret (not shown).
groupKey String Notifications with this same key will be grouped together as a single summary notification.
groupMessage string Summary text displayed in the summary notification.
actionButtons List List of action buttons on the notification.
fromProjectNumber String The Google project number the notification was sent under.
backgroundImageLayout BackgroundImageLayout If a background image was set this object will be available.
rawPayload String Raw JSON payload string received from Kontext.

ActionButton

OBJECT

List of action buttons on the notification. Part of OSNotificationPayload.

Parameter Type Description
id String Id assigned to the button.
text String Text show on the button to the user.
icon String Icon shown on the button.

BackgroundImageLayout

OBJECT

If a background image was set, this object will be available. Part of OSNotificationPayload.

Parameter Type Description
image String Image URL or name used as the background image.
titleTextColor String Text color of the title on the notification. ARGB Format.
bodyTextColor String Text color of the body on the notification. ARGB Format.

Opened Action

ANDROID MANIFEST

By default Kontext will open or resume your launcher Activity when a notification is tapped on. You can disable this behavior by adding the meta-data tag com.kontext.NotificationOpened.DEFAULT set to DISABLE inside your application tag in your AndroidManifest.xml.

1
2
3
<application ...>
   <meta-data android:name="com.kontext.NotificationOpened.DEFAULT" android:value="DISABLE" />
</application>

Make sure you are initializing Kontext with setNotificationOpenedHandler in the onCreate method in your Application class. You will need to call startActivity from this callback.

Appearance

enableVibrate

METHOD

By default Kontext always vibrates the device when a notification is displayed unless the device is in a total silent mode. Passing false means that the device will only vibrate lightly when the device is in it's vibrate only mode.

You can link this action to a UI button to give your user a vibration option for your notifications.

1
Kontext.enableVibrate(false);

enableSound

METHOD

By default Kontext plays the system's default notification sound when the device's notification system volume is turned on. Passing false means that the device will only vibrate unless the device is set to a total silent mode.

You can link this action to a UI button to give your user a different sound option for your notifications.

1
Kontext.enableSound(false);

Debug

setDebugLevel

METHOD

Enable logging to help debug if you run into an issue setting up Kontext. The following options are available with increasingly more information; NONE, INFO, DEBUG, VERBOSE

Parameter Type Description
logLevel LOG_LEVEL Sets the logging level to print to the Android LogCat log.
1
2
3
4
5
KontextAPI.setDebugLevel(KontextAPI.LogLevel.INFO);    //Default Log level

KontextAPI.setDebugLevel(KontextAPI.LogLevel.DEBUG);   //Set Log level to DEBUG log warnings or other important messages

KontextAPI.setDebugLevel(KontextAPI.LogLevel.OFF);     //Switch off logs for Production environment