Skip to main content

Android SDK

PushEngage Android SDK allows you to integrate Push Notification service into your Android applications. It can be used with both Kotlin and Java based native Android applications to integrate push notification using FCM.

info

This document shows the usage of the Android SDK and the ways to use the methods of the library.

Get SDK Version​

Retrieves the current version of the PushEngage Android SDK, returning a string that represents the SDK's current version.

Syntax​

getSdkVersion()

Returns​

A String representing the current version of the PushEngage Android SDK.

Usage​

PushEngage.getSdkVersion();

Request Notification Permission​

Requests notification permission from the user. For Android 13 (API 33) and above, this will show the system permission dialog. For older versions, the permission is automatically granted and the callback will be invoked with granted=true.

This method works with both ComponentActivity (Compose) and FragmentActivity. When permission is granted, the SDK automatically calls PushEngage.subscribe() for you, so you don't need to call it manually in the callback.

Syntax​

requestNotificationPermission(ComponentActivity activity, PushEngagePermissionCallback callback)

Parameters​

activity: The ComponentActivity (works with both Compose and traditional Activities)

callback: The PushEngagePermissionCallback callback to be invoked with the permission result

Usage​

// Works with ComponentActivity (Compose)
PushEngage.requestNotificationPermission(this, new PushEngagePermissionCallback() {
    @Override
    public void onPermissionResult(boolean granted, Error error) {
        if (granted) {
            Log.d("Permission", "User is now subscribed!");
        } else {
            // Handle permission denied
            Log.d("Permission", "Permission denied: " + error.getMessage());
        }
    }
});

Get Notification Permission Status​

Get the current notification permission status for the application. This method returns the permission status synchronously as a string.

Syntax​

getNotificationPermissionStatus()

Returns​

A String indicating the current notification permission state:

  • "granted": The application is authorized to post user notifications
  • "denied": The application is not authorized to post user notifications

Usage​

String permissionStatus = PushEngage.getNotificationPermissionStatus();
switch (permissionStatus) {
    case "granted":
        Log.d("Permission", "Notifications are allowed");
        break;
    case "denied":
        Log.d("Permission", "Notifications are denied");
        break;
    default:
        Log.d("Permission", "Unknown permission status");
        break;
}

Get Subscription Status​

Check whether the user is currently subscribed to push notifications.

Syntax​

getSubscriptionStatus(PushEngageResponseCallback callback)

Parameters​

callback: The callback to be invoked with the subscription status result.

  • result: A boolean indicating the user's subscription status.
    • Will be true if user is subscribed to push notifications.
    • Will be false if user is not subscribed (unsubscribed or never subscribed).

Usage​

PushEngage.getSubscriptionStatus(new PushEngageResponseCallback() {
    @Override
    public void onSuccess(Object result) {
        Boolean isSubscribed = (Boolean) result;
        if (isSubscribed) {
            Log.d("Subscription", "User is subscribed");
        } else {
            Log.d("Subscription", "User is not subscribed");
        }
    }

    @Override
    public void onFailure(Integer errorCode, String errorMessage) {
        Log.e("Subscription", "Error checking subscription: " + errorMessage);
    }
});

Get Subscription Notification Status​

Check whether the user can actually receive push notifications by verifying both subscription status and notification permission. The user can receive notifications only if they are subscribed AND the app has notification permission granted.

Syntax​

getSubscriptionNotificationStatus(PushEngageResponseCallback callback)

Parameters​

callback: The callback to be invoked with the subscription notification status.

  • result: A boolean indicating whether the user can receive notifications.
    • Will be true if user can receive notifications (subscribed AND permission granted).
    • Will be false if user cannot receive notifications (not subscribed or permission denied).

Usage​

PushEngage.getSubscriptionNotificationStatus(new PushEngageResponseCallback() {
    @Override
    public void onSuccess(Object result) {
        Boolean canReceiveNotifications = (Boolean) result;
        if (canReceiveNotifications) {
            Log.d("Subscription", "User can receive notifications");
        } else {
            Log.d("Subscription", "User cannot receive notifications");
        }
    }

    @Override
    public void onFailure(Integer errorCode, String errorMessage) {
        Log.e("Subscription", "Error checking notification status: " + errorMessage);
    }
});

Get Subscriber ID​

Retrieve the unique subscriber ID for a user. PushEngage generates this ID for every user based on their subscription data. Sometimes, this ID is referred to as the 'subscriber_hash'. The subscriber ID remains consistent unless there's a change in the user's subscription. If the user is not subscribed, it will return null.

Syntax​

getSubscriberId(PushEngageResponseCallback callback)

Parameters​

callback: The callback to be invoked with the subscriber ID result.

  • subscriberId: The unique subscriber ID for the user.
    • Will be a String containing the subscriber ID if the user is subscribed.
    • Will be null if the user is not subscribed.

Usage​

PushEngage.getSubscriberId(new PushEngageResponseCallback() {
    @Override
    public void onSuccess(Object result) {
        String subscriberId = (String) result;
        if (subscriberId != null) {
            Log.d("Subscriber", "Subscriber ID: " + subscriberId);
        } else {
            Log.d("Subscriber", "User is not subscribed");
        }
    }

    @Override
    public void onFailure(Integer errorCode, String errorMessage) {
        Log.e("Subscriber", "Error getting subscriber ID: " + errorMessage);
    }
});

Subscribe to Push Notifications​

Subscribe the user to push notifications. This method checks the current permission status and subscription state to determine the appropriate action. If notification permission is not granted, it will automatically request permission first. The callback will invoke onSuccess() when the user successfully subscribes or onFailure() if the subscription fails (including cases where permission is denied by the user).

Syntax​

subscribe(ComponentActivity activity, PushEngageResponseCallback callback)

Parameters​

activity: The ComponentActivity required for permission handling (works with both Compose and traditional Activities)

callback: The callback to be invoked with the subscribe result. Returns success or failure of the subscription operation.

Usage​

PushEngage.subscribe(this, new PushEngageResponseCallback() {
    @Override
    public void onSuccess(Object result) {
        Log.d("Subscription", "User subscribed successfully");
    }

    @Override
    public void onFailure(Integer errorCode, String errorMessage) {
        Log.e("Subscription", "Failed to subscribe: " + errorMessage);
    }
});

Unsubscribe from Push Notifications​

Unsubscribe the user from push notifications. This stops the user from receiving notifications but keeps their profile and preferences in the system. The user can be re-subscribed later using the subscribe() method.

Syntax​

unsubscribe(PushEngageResponseCallback callback)

Parameters​

callback: The callback to be invoked with the unsubscribe result.

  • result: A boolean indicating the unsubscription result.
    • Will be true if the unsubscription was successful.
    • Will be false if the unsubscription operation failed.

Usage​

PushEngage.unsubscribe(new PushEngageResponseCallback() {
    @Override
    public void onSuccess(Object result) {
        Log.d("Subscription", "User unsubscribed successfully");
    }

    @Override
    public void onFailure(Integer errorCode, String errorMessage) {
        Log.e("Subscription", "Failed to unsubscribe: " + errorMessage);
    }
});

Set Notification Small Icon​

Sets the resource name of the small icon used for notifications. The small icon appears in the status bar when a notification is displayed.

Syntax​

setSmallIconResource(String resourceName)

Parameters​

resourceName: A string representing the resource name of the small icon.

Usage​

String resourceName = "your_small_icon_name";

PushEngage.setSmallIconResource(resourceName);
note

It is recommended to set a valid resource name to ensure proper display of notifications. If an invalid resource name is provided, the default bell icon specified by the PushEngage library will be used.

Retrieve Subscriber Details​

This method retrieves subscriber details based on a provided list of strings, which can include city, state, country, device, device type, segments, etc.

Syntax​

getSubscriberDetails(List<String> values, PushEngageResponseCallback callback)

Parameters​

values: A list of strings that can contain any values from PushEngage.SubscriberFields.

callback: An interface designed as a callback to handle API responses asynchronously.

Usage​

List<String> subscriberDetailsList = new ArrayList<>();
subscriberDetailsList.add(PushEngage.SubscriberFields.City);
subscriberDetailsList.add(PushEngage.SubscriberFields.State);

PushEngage.getSubscriberDetails(subscriberDetailsList, new PushEngageResponseCallback() {
    @Override
    public void onSuccess(Object responseObject) {
       //Handle the success event.
    }

    @Override
    public void onFailure(Integer errorCode, String errorMessage) {
       //Handle the failure event.
    }
});

Profile ID to Subscriber​

Profile IDs serve as unique identifiers for your subscribers, enabling you to recognize them across multiple devices. Each subscriber can be assigned just one profile ID. This ID should be a string, and you have the flexibility to use any value, such as an email or phone number.

This method allows you to set a profile ID for the current subscriber. If a profile ID already exists, it will be replaced with the new value.

Syntax​

addProfileId(String profileId, PushEngageResponseCallback callback)

Parameters​

profileId: A String representing the profile ID to be associated with the subscriber.

callback(optional): An interface designed as a callback to handle API responses asynchronously.

Usage​

PushEngage.addProfileId("your_id", new PushEngageResponseCallback() {
    @Override
    public void onSuccess(Object responseObject) {
        //Handle the Success event.
    }

    @Override
    public void onFailure(Integer errorCode, String errorMessage) {
       //Handle the Failure event.
    }
});

Automated/Personalized Notifications​

Automated notifications include all types of triggered campaigns, such as cart abandonment, price drop, back in stock, and browse abandonment. By default, automated notifications are enabled for all subscribers.

Enable/Disable Automated Notifications for Subscriber​

This method allows you to enable/disable automated notifications for the current subscriber.

Syntax​

automatedNotification(TriggerStatusType status, PushEngageResponseCallback callback)

Parameters​

status: The trigger status type indicating the status of the trigger campaign.

callback: An interface designed as a callback to handle API responses asynchronously.

Usage​

Enable Automated Notifications

PushEngage.automatedNotification(PushEngage.TriggerStatusType.enabled, new PushEngageResponseCallback() {
    @Override
    public void onSuccess(Object responseObject) {
        Toast.makeText(TriggerCampaignActivity.this, "Trigger Enabled Successfully", Toast.LENGTH_LONG).show();
    }

    @Override
    public void onFailure(Integer errorCode, String errorMessage) {
        Toast.makeText(TriggerCampaignActivity.this, "Trigger Enabled Failed", Toast.LENGTH_LONG).show();
    }
});

Disable Automated Notifications

PushEngage.automatedNotification(PushEngage.TriggerStatusType.disabled, new PushEngageResponseCallback() {
    @Override
    public void onSuccess(Object responseObject) {
        Toast.makeText(TriggerCampaignActivity.this, "Trigger Enabled Successfully", Toast.LENGTH_LONG).show();
    }

    @Override
    public void onFailure(Integer errorCode, String errorMessage) {
        Toast.makeText(TriggerCampaignActivity.this, "Trigger Enabled Failed", Toast.LENGTH_LONG).show();
    }
});

Goal Tracking​

Goal Tracking will help you assign conversion goals & value to your notification campaigns. You can set up a default goal and have it integrated for all your campaigns.

Syntax​

sendGoal(Goal goal, PushEngageResponseCallback callback)

Parameters​

goal: Goal object representing the goal to be tracked.

callback: An interface designed as a callback to handle API responses asynchronously.

Usage​

Goal goal = new Goal("name_of_goal", 1, 10.0);
PushEngage.sendGoal(goal, new PushEngageResponseCallback() {
    @Override
    public void onSuccess(Object responseObject) {
        Toast.makeText(GoalActivity.this, "Goal Added Successfully", Toast.LENGTH_LONG).show();
    }

    @Override
    public void onFailure(Integer errorCode, String errorMessage) {
        Toast.makeText(GoalActivity.this, "Failure", Toast.LENGTH_LONG).show();
    }
});

Triggered Campaigns​

Custom Trigger Campaign​

Detect your visitor’s behavior to send automated push notifications to the right person at the right time.

Syntax​

sendTriggerEvent(TriggerCampaign trigger, PushEngageResponseCallback callback)

Parameters​

triggerCampaign: The TriggerCampaign object representing the campaign event to be triggered.

callback: An interface designed as a callback to handle API responses asynchronously.

Usage​

Map<String, String> dataMap = new HashMap<>();
dataMap.put("custom_key", "custom_value");
TriggerCampaign triggerCampaign = new TriggerCampaign(
    "name_of_campaign",
    "name_of_event",
    "your_reference_id", // optional
    dataMap // optional
);

PushEngage.sendTriggerEvent(triggerCampaign, new PushEngageResponseCallback() {
    @Override
    public void onSuccess(Object responseObject) {
        Toast.makeText(TriggerEntryActivity.this, "Send Trigger Alert Successfully", Toast.LENGTH_LONG).show();
    }

    @Override
    public void onFailure(Integer errorCode, String errorMessage) {
        Toast.makeText(TriggerEntryActivity.this, errorMessage != null ? errorMessage : "Error occurred", Toast.LENGTH_LONG).show();
    }
});

Trigger Alert​

Re-engage your customers and increase conversion using Price Drop Alert Campaigns and Inventory Alert Campaigns.

addAlert(TriggerAlert alert, PushEngageResponseCallback callback)

Parameters​

alert: The TriggerAlert object representing the alert to be added.

callback: An interface designed as a callback to handle API responses asynchronously.

Usage​

Price Drop

Map<String, String> dataMap = new HashMap<>();
dataMap.put("custom_key", "custom_value");

TriggerAlert triggerAlert = new TriggerAlert(
    TriggerAlertType.priceDrop,
    "your_product_id",
    "your_link",
    100.0,
    "your_variant_id", // optional
    "your_expiry_timestamp", // optional
    102.0, // optional
    .inStock, // optional, possible values: [.inStock, .outOfStock]
    dataMap // optional
);

PushEngage.addAlert(triggerAlert, new PushEngageResponseCallback() {
    @Override
    public void onSuccess(Object responseObject) {
        Toast.makeText(AddAlertActivity.this, "Add Alert Successfully", Toast.LENGTH_LONG).show();
    }

    @Override
    public void onFailure(Integer errorCode, String errorMessage) {
        Toast.makeText(AddAlertActivity.this, errorMessage, Toast.LENGTH_LONG).show();
    }
});

Back in Stock Alert

Map<String, String> dataMap = new HashMap<>();
dataMap.put("custom_key", "custom_value");

TriggerAlert triggerAlert = new TriggerAlert(
    TriggerAlertType.inventory,
    "your_product_id",
    "your_link",
    100.0,
    "your_variant_id", // optional
    "your_expiry_timestamp", // optional
    .inStock, // optional, possible values: [.inStock, .outOfStock]
    dataMap // optional
);

PushEngage.addAlert(triggerAlert, new PushEngageResponseCallback() {
    @Override
    public void onSuccess(Object responseObject) {
        Toast.makeText(AddAlertActivity.this, "Add Alert Successfully", Toast.LENGTH_LONG).show();
    }

    @Override
    public void onFailure(Integer errorCode, String errorMessage) {
        Toast.makeText(AddAlertActivity.this, errorMessage, Toast.LENGTH_LONG).show();
    }
});

Segments​

Segments are used to group subscribers so that you can send personalized notifications. Segments can be created based on attributes, categories, and more.

Add a Subscriber to Segments​

This method enables you to add the current subscriber to segments.

Syntax​

addSegment(List<String> segmentId, PushEngageResponseCallback callback)

Parameters​

segmentId: A list of segment IDs to be added.

callback(optional): An interface designed as a callback to handle API responses asynchronously.

Usage​

List<String> segmentList = new ArrayList<String>();
segmentList.add("sports");

PushEngage.addSegment(segmentList, new PushEngageResponseCallback() {
    @Override
    public void onSuccess(Object responseObject) {
    //Handle the Success event.
    }

    @Override
    public void onFailure(Integer errorCode, String errorMessage) {
    //Handle the Failure event.
    }
});

Add a Subscriber to a Segment with Duration​

This method enables you to add the current subscriber to a segment for a specified duration, measured in days. After this period, the segment will be automatically removed from the subscriber.

Syntax​

addDynamicSegment(List<AddDynamicSegmentRequest.Segment> segments, PushEngageResponseCallback callback)

Parameters​

segments: A list of segment objects representing dynamic segments to be added.

  • Contains the segment data to be associated with the user.

callback (optional): An interface designed as a callback to handle API responses asynchronously.

  • Called when the operation completes with success or failure information.

Usage​

AddDynamicSegmentRequest addDynamicSegmentRequest = new AddDynamicSegmentRequest();
List<AddDynamicSegmentRequest.Segment> segments = new ArrayList<>();
AddDynamicSegmentRequest.Segment segment = addDynamicSegmentRequest.new Segment("sports", 5);
segments.add(segment);

PushEngage.addDynamicSegment(segments, new PushEngageResponseCallback() {
    @Override
    public void onSuccess(Object responseObject) {
       //Handle the Success event.
    }

    @Override
    public void onFailure(Integer errorCode, String errorMessage) {
       //Handle the Failure event.
    }
});

Remove a Subscriber from Segments​

This method allows you to remove the current subscriber from segments.

Syntax​

removeSegment(List<String> segmentId, PushEngageResponseCallback callback)

Parameters​

segmentId: A list of segment IDs to be removed.

callback(optional): An interface designed as a callback to handle API responses asynchronously.

Usage​

List<String> segmentList = new ArrayList<String>();
segmentList.add("sports");

PushEngage.removeSegment(segmentList, new PushEngageResponseCallback() {
    @Override
    public void onSuccess(Object responseObject) {
       //Handle the Success event.
    }

    @Override
    public void onFailure(Integer errorCode, String errorMessage) {
       //Handle the Failure event.
    }
});

Attributes​

Attributes are key-value pairs that allow you to store additional information about your subscribers. You can utilize attributes to segment your subscribers and send personalized notifications.

Add Attributes to Subscriber​

Use this method to add or update attributes for a subscriber. If an attribute with the specified key already exists, the existing value will be replaced.

Syntax​

addSubscriberAttributes(JSONObject obj, PushEngageResponseCallback callback)

Parameters​

obj: A JSONObject containing the subscriber attributes to be added.

callback(optional): An interface designed as a callback to handle API responses asynchronously.

Usage​

try {
    JSONObject jsonObject = new JSONObject();
    jsonObject.put("age", "25");
    jsonObject.put("height", "6.1");

    PushEngage.addSubscriberAttributes(jsonObject, new   PushEngageResponseCallback() {
        @Override
        public void onSuccess(Object responseObject) {
          //Handle the Success event.
        }

        @Override
        public void onFailure(Integer errorCode, String errorMessage) {
        //Handle the Failure event.
        }
    });
    } catch (JSONException e) {
           e.printStackTrace();
    }

Set Attributes for Subscriber​

This method allows you to set attributes for a subscriber, replacing any previously associated attributes. Use this method when you need to entirely reset the attributes with new values.

Syntax​

setSubscriberAttributes(JSONObject obj, PushEngageResponseCallback callback)

Parameters​

obj: A JSONObject containing the updated subscriber attributes.

callback(optional): An interface designed as a callback to handle API responses asynchronously.

Usage​

try {
    JSONObject jsonObject = new JSONObject();
    jsonObject.put("age", "25");
    jsonObject.put("height", "6.1");

    PushEngage.setSubscriberAttributes(jsonObject, new   PushEngageResponseCallback() {
        @Override
        public void onSuccess(Object responseObject) {
          //Handle the Success event.
        }

        @Override
        public void onFailure(Integer errorCode, String errorMessage) {
        //Handle the Failure event.
        }
    });
    } catch (JSONException e) {
           e.printStackTrace();
    }

Get Attributes for Subscriber​

Retrieve the attributes associated with the current subscriber using this method.

Syntax​

getSubscriberAttributes(PushEngageResponseCallback callback)

Parameters​

callback: An interface designed as a callback to handle API responses asynchronously.

  • result: The subscriber attributes data.
    • Will contain the user's attributes if successfully retrieved.
    • Will be null if no attributes are found or retrieval fails.

Usage​

PushEngage.getSubscriberAttributes(new PushEngageResponseCallback() {
    @Override
    public void onSuccess(Object responseObject) {
        //Handle the Success event.
    }

    @Override
    public void onFailure(Integer errorCode, String errorMessage) {
       //TODO Handle the Failure event.
    }
});

Remove Attributes for Subscriber​

This method allows you to remove one or more attributes from the current subscriber. Provide an array of attribute names you wish to remove. Passing an empty array will result in the removal of all the subscriber's attributes.

Syntax​

deleteSubscriberAttributes(List<String> values, PushEngageResponseCallback callback)

Parameters​

values: A List<String> containing attribute names to be deleted.

callback(optional): An interface designed as a callback to handle API responses asynchronously.

Usage​

List<String> attributeList = new ArrayList<>();
attributeList.add("age");
attributeList.add("height");

PushEngage.deleteSubscriberAttributes(attributeList, new PushEngageResponseCallback() {
    @Override
    public void onSuccess(Object responseObject) {
       //Handle the Success event.
    }

    @Override
    public void onFailure(Integer errorCode, String errorMessage) {
       //Handle the Failure event.
    }
});
Last updated on