Location Triggers (SSP) - rezolved/rezolve_sdk_sampleapp_android GitHub Wiki

Location Triggers are a powerful SDK feature introduced in 2020 that allows the developer to detect when the consumer has entered a predefined geozone and pop a notification of a product, informational page, or Act. A geozone is defined as a radius of X meters around a specified lat/long point, as set up by a merchant or partner in the Rezolve portal.

When the app is active, the SDK continuously samples the consumer's location, and when the consumer is within the radius of one or more geozones, events fire to alert the system to perform the desired behavior. The SDK intelligently handles areas with a high density of overlapping geozones to prevent spamming the user with notifications. If the consumer is in an area with multiple geozones, the SDK bundles multiple notifications into one alert that contains the messages from all the relevant zones.

Setup location detection

This section describes how to set up your project to use the location features of the Rezolve SDK. In addition to dependencies listed here you will also need to add this dependency in your gradle config to use SSP Location Triggers

dependencies {
    def rezolveSdkVersion = "3.2.0"
    implementation "com.rezolve.sdk:old-ssp-android:$rezolveSdkVersion"
    // ...
}

Initializing location detection

Initializing location detection requires setting up the SspActManager with appropriate settings. Click here for details.

// Taken from App.java in the Sample App project 

// Create and start Location Provider
// Make sure you have secured the location permission before starting the location provider.
final LocationProviderFused locationProviderFused = LocationProviderFused.create(this, notification);
locationProviderFused.start();

// Next, set up Geofence detection and Resolvers 

// Set up SspActManager 
SspActManager sspActManager = new SspActManager(httpClient, rezolveSDK);

// Set up Rezolve Configuration Builder (this also supports the image/audio Scanner function)
new ResolverConfiguration.Builder(rezolveSDK)
    .enableBarcode1dResolver(true)
    .enableCoreResolver(true)
    .enableSspResolver(sspActManager, 400)
    .build(this);

// Set up GeofenceMananger
final GeofenceManager geofenceManager = new GeofenceManager.Builder()
    .sspActManager(sspActManager)
    .engagementsUpdatePolicy(new EngagementsUpdatePolicy.Builder()
        .silencePeriodMS(TimeUnit.MINUTES.toMillis(5))
        .maxCacheTimeMS(TimeUnit.MINUTES.toMillis(5))
        .build())
    .notificationChannelPropertiesList(geofenceLocationChannels)
    .engagementAlertNotification(geofenceAlertNotificationProperties)
    .context(this)
    .build();

GeofenceManager.Builder also gives an option to provide custom SspGeofenceDetector. If you want to use default implementation, based on Google Geofencing Client simply add this dependency:

dependencies {
   implementation "com.rezolve.sdk:ssp-google-geofence:$rezolveSdkVersion"
}

Detecting geozones

During detection, the user's location is monitored. Detection times vary according to OS settings.

The specific threshold distances are determined by the hardware and the location technologies that are currently available. For example, if Wi-Fi is disabled, region monitoring is significantly less accurate. However, for testing purposes, you can assume that the minimum distance is approximately 200 meters."

// Taken from App.java in the Sample App project 

// Make sure the location provider is started before detection.
// Based on the provided EngagementsUpdatePolicy  the GeofenceManager will manage geofence updates

final GeofenceManager geofenceManager = new GeofenceManager.Builder()
                .sspActManager(sspActManager)
                .engagementsUpdatePolicy(new EngagementsUpdatePolicy.Builder().build())
                .notificationChannelPropertiesList(geofenceLocationChannels)
                .engagementAlertNotification(geofenceAlertNotificationProperties)
                .context(this)
                .build();
registerGeofenceListener();
locationProviderFused.start();
geofenceManager.startGeofenceTracking();

geofenceManager.addEngagementListener(list -> Log.d(TAG, "onGeolocationTriggeredEngagementUpdate: " + list));
GeozoneNotificationCallbackHelper.getInstance().addCallback(new GeozoneNotificationCallback() {
    @Override
    public void onDisplayed(@NonNull String title, @NonNull String subtitle, @NonNull String engagementId, @NonNull String actId) {
        //Handle notification displayed event
    }

    @Override
    public void onError(@NonNull RezolveError error, @NonNull String engagementId) {
        //Handle error
    }

    @Override
    public boolean onSelected(@NonNull SspObject sspObject) {
        Log.d(TAG, "onSelected: " + sspObject);
        if (sspObject instanceof SspAct) {
            SspAct act = (SspAct)sspObject;
            if (act.getPageBuildingBlocks() != null && !act.getPageBuildingBlocks().isEmpty()) {
                navigateToSspActView(act);
            }
        }
        return false;
    }
});

Handling detection and notification

When a geofence is detected, notification is potentially shown, as long as it is not within a silent period from a previous detection.

// Taken from App.java in the Sample App project 

// The SDK sends the following broadcast messages (see code sample in "Detecting Geozones" above for details):

// When the notification is displayed in the notification center, the broadcast action is set to: 
ACTION_GEOFENCE_NOTIFICATION_DISPLAYED:

// And when the user taps the notification, the broadcast action is set to: 
ACTION_GEOFENCE_NOTIFICATION_SELECTED:

// Notes:
// The SDK shows a notification when it detects the geofence zone. 
// The SDK calls the server endpoint to get the object details, and if the object is active
//   it will show the notification and send the ACTION_GEOFENCE_NOTIFICATION_DISPLAYED broadcast.
// Use the geofenceBroadcastReceiver to fetch details about the trigger and SspObject.
// The fetched ssp object has to be in an active state for notification to be shown. 
// The SDK prevents showing duplicate notifications if the same geofence was detected 
//   during the silent period defined in the EngagementsUpdatePolicy.

Notification handling

By default the shown geofence notification is presented with a system notification. If you want to handle it in a different way or to filter it somehow you need to pass EngagementEventListener to GeofenceManager.Builder():

GeofenceManager.Builder builder;
builder.engagementEventListener(sspObject -> {
    //Your event handling/filtering
});

When EngagementEventListener is set default behaviour (showing notification) is disabled so only your listener gets triggered

Getting geofences

You can get directly information about nearby geofences by using SspActManager.getSspGeofenceEngagements

LocationWrapper locationWrapper;
CoordinateSystem coordinateSystem;
int radius;
long minutesFurther;
String since;
int limit;
int offset;
sspActManager.getSspGeofenceEngagements(locationWrapper, coordinateSystem, radius, minutesFurther, since, limit, offset, new SspGeofenceEngagementsInterface() {
    @Override
    public void onGetSspGeofenceEngagementsSuccess(EngagementResponse<GeolocationTriggeredEngagement> engagementResponse) {
        List<GeolocationTriggeredEngagement> geolocationTriggeredEngagements = engagementResponse.getSspEngagementsBundle().getData();
    }

    @Override
    public void onError(@NonNull RezolveError rezolveError) {
        //Handle error
    }
});