Skip to main content

Android SDK Reference

Complete API reference for the PushEngage Android SDK. For setup and installation, see the Android Quickstart.

The SDK supports Java and Kotlin. Android API 16 (Android 4.1) or higher is required; API 21+ recommended.

GitHub release

Initialization​

PushEngage.Builder​

Initializes the SDK. Call this once in your Application.onCreate() before using any other SDK feature. The builder registers the application context and your App ID, and build() installs the SDK singleton. The App ID can be obtained from your PushEngage Dashboard under Site Settings → Installation → Android SDK.

note

This must be called before using any other SDK features. It associates all subsequent operations with your specific PushEngage application.

Syntax​

new PushEngage.Builder()
    .addContext(Context context)
    .setAppId(String appId)
    .build()

Parameters​

context: Your application Context. Required — if omitted, build() logs an error and returns null without initializing the SDK. The SDK stores the application context internally, so passing an Activity does not leak it.

appId: A String representing the App ID from your PushEngage Dashboard. If null or blank, initialization still completes but the SDK logs an error and skips sync and subscriber requests until a valid App ID is configured.

Usage​

public class PEApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        PushEngage pushEngage = new PushEngage.Builder()
                .addContext(getApplicationContext())
                .setAppId("YOUR_APP_ID")
                .build();
    }
}
Re-initialization

Calling build() again is safe and refreshes the configuration. If the App ID differs from the previous build, the SDK clears the cached subscriber state and re-registers the device against the new App ID on the next sync. Calling build() with an invalid App ID preserves a previously stored valid one.

Notification Permission​

requestNotificationPermission​

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());
        }
    }
});

getNotificationPermissionStatus​

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;
}

Subscription​

subscribe​

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​

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);
    }
});

getSubscriptionStatus​

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);
    }
});

getSubscriptionNotificationStatus​

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);
    }
});

Associate Profile ID​

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.

getSubscriberId​

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);
    }
});

addProfileId​

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.
    }
});

User Identity​

The identify and logout methods manage the predefined personal-data fields stored on the current subscriber. Use them to tie a push subscription to your own first-party user data, and to clear that data on sign-out without unsubscribing the device.

The 12 valid keys are: first_name, last_name, email, phone, gender, dob, language, profile_id, country, city, state, zip. Values must be String, Number, or Boolean — other types are rejected client-side.

identify​

Upsert one or more of the 12 predefined subscriber fields. If every requested field already matches the locally cached value (and the cache is fresh — within 24 hours of the last successful sync), the call short-circuits with onSuccess(null) and no network request is sent. A numeric profile_id is coerced to its string form before being sent.

Syntax​

identify(JSONObject fields, PushEngageResponseCallback callback)

Parameters​

fields: A JSONObject containing one or more of the 12 valid subscriber fields. Must contain at least one key.

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

Usage​

try {
    JSONObject fields = new JSONObject();
    fields.put("first_name", "Jane");
    fields.put("last_name", "Doe");
    fields.put("email", "[email protected]");
    fields.put("profile_id", "user_12345");

    PushEngage.identify(fields, 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();
}

logout​

Remove a set of predefined personal fields from the current subscriber while keeping the device subscribed for push. Call this when a user signs out of your app to detach their PII from the push subscription.

Passing null or an empty list removes the default PII field set: first_name, last_name, email, phone, gender, dob, profile_id. Passing a list of field names scopes the removal to those specific fields.

If none of the requested field names exist in the locally cached subscriber data (and the cache is fresh — within 24 hours of the last successful sync), the call short-circuits with onSuccess(null) and no network request is sent.

Syntax​

logout(List<String> fieldNames, PushEngageResponseCallback callback)

Parameters​

fieldNames: A List<String> of field names to remove. Pass null or an empty list to clear the default PII set.

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

Usage​

Clear the default PII set:

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

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

Clear specific fields:

List<String> fieldsToClear = new ArrayList<>();
fieldsToClear.add("email");
fieldsToClear.add("phone");

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

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

Subscriber Details​

getSubscriberDetails​

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.
    }
});

Available Fields​

FieldTypeDescription
citystringSubscriber's city
statestringSubscriber's state or region
countrystringSubscriber's country
devicestringDevice name
device_typestringDevice type (e.g., mobile, tablet)
user_agentstringApp user agent string
hoststringHost identifier
timezonestringSubscriber's timezone
has_unsubscribedbooleanWhether the subscriber has unsubscribed
ts_createdstringISO 8601 timestamp of subscription creation
segmentsarraySegment IDs the subscriber belongs to

Segments​

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

addSegment​

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.
    }
});

addDynamicSegment​

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.
    }
});

removeSegment​

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.

addSubscriberAttributes​

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();
    }

setSubscriberAttributes​

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();
    }

getSubscriberAttributes​

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) {
       // Handle the Failure event.
    }
});

deleteSubscriberAttributes​

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.
    }
});

Automated 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.

automatedNotification​

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 Disabled Successfully", Toast.LENGTH_LONG).show();
    }

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

Triggered Campaigns​

sendTriggerEvent​

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​

trigger: 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", // referenceId (optional)
    null,                // profileId (optional)
    dataMap              // data (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();
    }
});

addAlert​

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

Syntax​

addAlert(TriggerAlert alert, PushEngageResponseCallback callback)

Parameters​

alert: A TriggerAlert object describing the alert. All positional fields must be provided when constructing from Java; Kotlin callers may use named parameters and omit optional fields.

FieldTypeRequiredDescription
typePushEngage.TriggerAlertTypeYesAlert type: priceDrop or inventory
productIdStringYesUnique identifier for the product
linkStringYesURL to the product page
priceDoubleYesCurrent price of the product
variantIdString?NoProduct variant identifier
expiryTimestampDate?NoWhen the alert expires
alertPriceDouble?NoTarget price that triggers the alert. Omitted from the request when null; the server may apply a default.
availabilityPushEngage.TriggerAlertAvailabilityType?NoinStock or outOfStock. Omitted from the request when null; the server may apply a default.
profileIdString?NoAssociate the alert with a specific subscriber profile
mrpDouble?NoMaximum retail price of the product
dataMap<String, String>?NoCustom key-value pairs to attach to the alert

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(
    PushEngage.TriggerAlertType.priceDrop,           // type
    "product_id",                               // productId
    "product_link",                                     // link
    100.0,                                           // price
    "product_variant_id",                               // variantId (optional)
    null,                                            // expiryTimestamp: Date (optional)
    102.0,                                           // alertPrice (optional)
    PushEngage.TriggerAlertAvailabilityType.inStock, // availability (optional)
    null,                                            // profileId (optional)
    null,                                            // mrp (optional)
    dataMap                                          // data (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(
    PushEngage.TriggerAlertType.inventory,              // type
    "product_id",                                       // productId
    "product_link",                                     // link
    100.0,                                              // price
    "product_variant_id",                               // variantId (optional)
    null,                                               // expiryTimestamp: Date (optional)
    null,                                               // alertPrice (optional)
    PushEngage.TriggerAlertAvailabilityType.outOfStock, // availability (optional; omitted when null, server may default)
    null,                                            // profileId (optional)
    null,                                            // mrp (optional)
    dataMap                                          // data (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();
    }
});

In-App Messaging​

Display in-app messages authored on the PushEngage dashboard. Requires Android SDK 1.0.0+.

In-app messaging is a separate channel from push: it needs only an App ID, and works without a push subscription or notification permission. No additional setup is required — the SDK tracks activities itself and handles configuration changes. For trigger semantics, action types, frequency caps and troubleshooting, see the In-App Messaging guide.

triggerIAMEvent​

Reports a custom trigger event. Campaigns whose trigger event name matches, and whose trigger conditions the supplied parameters satisfy, are evaluated against their date window, frequency cap and audience rules, then displayed if eligible.

Campaigns with an app open trigger are fired by the SDK itself and need no call.

Syntax​

triggerIAMEvent(String eventName)
triggerIAMEvent(String eventName, Map<String, Object> parameters)
triggerIAMEvent(String eventName, Map<String, Object> parameters, PushEngageResponseCallback callback)

Parameters​

eventName: The trigger event name. Pass the exact string configured as the campaign's trigger event on the dashboard, including its casing. Required and must be non-empty — an empty name matches no campaign, so the SDK rejects it with 400 Event name is required rather than reporting a silent success.

parameters (optional): Data used to evaluate the campaign's trigger conditions. Every value is converted to its string form before matching, so give numeric comparisons a number-typed condition on the dashboard — both sides are then parsed rather than compared as text. Parameters that no condition names are ignored. Use strings, numbers or booleans as values; other types aren't supported for matching. Pass null if not needed.

callback (optional): An interface designed as a callback to handle the result asynchronously. onSuccess reports that the event was accepted for processing — not that a message was displayed.

Usage​

// Simplest form
PushEngage.triggerIAMEvent("app_launched");

// With parameters and a callback
Map<String, Object> parameters = new HashMap<>();
parameters.put("cart_value", 120);
parameters.put("currency", "USD");

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

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

setIAMCustomActionHandler​

Registers the handler that receives custom action buttons tapped inside a displayed message.

The SDK handles Open URL, Dismiss and Request notification permission buttons itself — only Custom action buttons reach this handler. The message is dismissed after the handler is notified. The SDK doesn't act on a custom action itself; to open a link, use an Open URL action instead.

If no handler is registered, a custom button tap is still recorded as a click and still closes the message.

Syntax​

setIAMCustomActionHandler(IAMCustomActionHandler handler)

Where IAMCustomActionHandler declares:

void onCustomAction(String actionId, Map<String, ?> parameters)

Parameters​

handler: An IAMCustomActionHandler from com.pushengage.pushengage.iam.action. Pass null to remove the current handler.

You may register the handler before PushEngage.Builder.build() runs — it is remembered and applied once in-app messaging is ready.

Usage​

import com.pushengage.pushengage.iam.action.IAMCustomActionHandler;

PushEngage.setIAMCustomActionHandler((actionId, parameters) -> {
    switch (String.valueOf(parameters.get("action"))) {
        case "view_cart":
            navigateToCart();
            break;
        case "open_offers":
            showOffers();
            break;
    }
});
Notification-permission buttons need no host code

If a campaign uses a Request notification permission button, do not forward onRequestPermissionsResult to the SDK. The SDK requests the permission and receives the system result itself, whatever type of activity hosts the message, and subscribes the user automatically on grant.

Custom Events​

trackEvent​

Track a custom event for the current subscriber. Custom events are used to start or exit campaign workflows based on in-app activity — for example, adding an item to cart, completing a purchase, or any other action you define. Workflows are configured from the PushEngage Dashboard.

Syntax​

trackEvent(TrackEvent event, PushEngageResponseCallback callback)

Parameters​

event: A TrackEvent object describing the event payload.

FieldTypeRequiredDescription
eventNameStringYesName of the event (e.g., "MySite.AddToCart").
dataMap<String, Object>NoCustom key-value data. Values must be strings, numbers, or booleans — other types are rejected client-side with error code 400 before any network request is made.
profileIdStringNoThe profile ID of the subscriber.
providerStringNoProvider name. Defaults to "PushEngage".
eventTypeStringNoEvent type. Defaults to "PushEngage.CustomEvent".

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

Usage​

Map<String, Object> eventData = new HashMap<>();
eventData.put("product_id", "123");
eventData.put("product_name", "Product Name");
eventData.put("price", 49.99);

TrackEvent event = new TrackEvent("MySite.AddToCart", eventData);

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

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

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.

sendGoal​

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();
    }
});

Utilities​

getSdkVersion​

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();

setSmallIconResource​

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.

setBadgeCount​

Control the numeric badge associated with notifications the SDK builds afterwards. Android does not expose a system API for a numeric launcher-icon badge — only a dot indicator on supported launchers, plus a count surfaced in the long-press shortcut menu.

  • count == 0 — clears all active notifications, which removes the launcher dot.
  • count > 0 — applied via NotificationCompat.Builder.setNumber(count) to notifications the SDK builds afterwards; the value appears in the long-press menu.
  • Negative values are coerced to 0.

Syntax​

setBadgeCount(int count)

Parameters​

count: The badge count to set. Use 0 to clear.

Usage​

PushEngage.setBadgeCount(5);

// Clear the badge
PushEngage.setBadgeCount(0);

setFcmConfigErrorListener​

Register a callback that fires when the SDK detects a mismatch between your app's local Firebase configuration and the configuration registered for your PushEngage site. Use this during integration to catch sender-ID or project-ID drift early — when a mismatch is detected at sync time, the SDK also skips the subscriber-add call so a permanently-undeliverable subscriber is not created on the server.

The listener is invoked with one of these error codes:

CodeConstantMeaning
5001FCM_SENDER_ID_MISMATCHgoogle-services.json sender ID does not match the PushEngage dashboard.
5002FCM_PROJECT_ID_MISMATCHgoogle-services.json project ID does not match the service-account JSON.
5003FCM_LOCAL_CONFIG_INVALIDFirebase Installations rejected google-services.json as invalid for the app.
5004FCM_CONFIG_BOTH_MISMATCHBoth sender ID and project ID differ from the dashboard configuration.
note

The listener may be invoked on a background thread (OkHttp dispatcher, Firebase Installations callback, or the caller's thread). Marshal to the UI thread before touching UI.

Pass null to clear a previously-registered listener.

Syntax​

setFcmConfigErrorListener(FcmConfigErrorListener listener)

Parameters​

listener: The FcmConfigErrorListener to invoke on config errors, or null to clear.

Usage​

PushEngage.setFcmConfigErrorListener(new FcmConfigErrorListener() {
    @Override
    public void onFcmConfigError(int errorCode, String message) {
        Log.e("PushEngage", "FCM config error " + errorCode + ": " + message);
    }
});

enableLogging​

Enables or disables verbose debug logging for the SDK. When enabled, the SDK prints detailed logs to Logcat that are useful for diagnosing integration issues.

danger

Disable logging in production builds to avoid leaking internal SDK state to device logs.

Syntax​

enableLogging(boolean shouldEnable)

Parameters​

shouldEnable: Pass true to turn on debug logging, false to turn it off.

Usage​

// Enable during development
PushEngage.enableLogging(true);

// Disable for production
PushEngage.enableLogging(false);
Last updated on