DashboardiOSAndroidA8 Media PlayerConsumer APIManagement API
Guides
These docs are for v1.2. Click to read the latest docs for v1.3.

Workflows

Suggest Edits

Workflows & Examples

The following sections illustrate the implementation of basic use cases you may want to refer when integrating the ACTV8me Android SDK into your project. Although you may choose from other content types, the examples are based on the delivery of redeemable offers.

Initialize SDK

You can initialize ACTV8me SDK using the init(Context context, strApiKey, strApiBaseUrl) method written in the me.actv8.core.CoreLibrary class. This is the first method that should be called to initialize the CoreLibrary.

In order to do so, you must include the following method call within your onCreate() method of Activity:

CoreLibrary.getInstance().init(this, String strApiKey, String strApiBaseUrl, int updateDevicePeriod);

Notes:

  1. The values for the strApiKey and strApiBaseUrl are provided by ACTV8me upon registration.
  2. The updateDevicePeriod can be set to any value representing the number of seconds between each request to update device metadata. The minimum value is 60 seconds and the default value is 300 seconds (5 minutes).

📘

This method should only be called once per application start (before calling any other method from ACTV8me SDK).

Add application settings listener

The SDK makes periodic requests to the backend to update device information and retrieve application settings.

In order to be notified by the application settings get retrieved, the Activity needs to implement the interface me.actv8.core.util.GetApplicationSettingsListener and override the onApplicationSettingsRetrieval method:

// NOTE: Your class must implement the "Actv8CallbackInterface.GetApplicationSettingsListener" interface

CoreLibrary.getInstance().addApplicationSettingsListener(this);

@override
    public void onApplicationSettingsRetrieval() {
        // Your code here
    }

You can also use the following method to update device metadata at your request (i.e. when the application enters the foreground):

CoreLibrary.getInstance().updateDeviceInfo();

User Authentication

Although optional, certain features of the ACTV8me platform (i.e. digital wallet) require the user to be authenticated. Therefore, you may want to provide authentication to uniquely identify your users. If so, refer to code snippets below for examples on basic authentication logic.

If you do not currently have an authentication server for your application, you can leverage the ACTV8me Oauth 2.0 server to authenticate your users.

The following section illustrates basic authentication logic.

Create User

To create a new user, you may call the following method:

CoreLibrary.getInstance().createUser(UserPii user, String password)

In order to be notified by the result of the createUser() method, the Activity needs to implement the interface me.actv8.core.util.Actv8CallbackInterface.OnCreateUserListener. This interface has one abstract method:

void onCreateUser(ServerResponseObject response);

In the method above, the ServerResponseObject contains the actual response from the server.

In order to use the OnCreateUserListener, you need to add the line below to the onCreate() method of the Activity implementing it:

CoreLibrary.getInstance().addOnCreateUserListener(this);

and the line below in the onDestroy() method of the implementing activity:

CoreLibrary.getInstance().removeOnCreateUserListener(this);

Note:
When registering a new user, the DOB (date of birth) and gender must follow these format:

  1. DOB: "yyyy-MM-dd" (string) format .
  2. Gender: 1 (int) for "male" and 2 (int) for "female".

If your application already has an authentication provider, you may refer to the Syndicated Login method (read below).

Login User (email)

Users that have been registered via the ACTV8me authentication service can be logged in via the following method:

CoreLibrary.getInstance().login (UserPii user, String password)

Note:
Set "email" and "login_method" fields in the UserPii object and "password" as separate parameter.

📘

“CoreLibrary.getInstance().getCurrentUser() != null”

can be called to find if the user is logged or not. This method returns a Actv8User object type.

In order to be notified by the Login result, the Activity needs to implement the interface "me.actv8.core.util.Actv8CallbackInterface.OnUserLoginListener". The OnUserLoginListener interface has one abstract method:

void onUserLogin(ServerResponseObject response);

In the above method ServerResponseObject is the actual response from the server.

In order to use the OnUserLoginListener, you must add the following line to the onCreate() method of the implementing Activity:

CoreLibrary.getInstance().addOnUserLoginListener(this);

and the line below in the onDestroy() method of the implementing activity:

CoreLibrary.getInstance().removeOnUserLoginListener(this);

Thi CoreLibrary.getInstance().login (UserPii user, String password) endpoint is used to validate user credentials and retrieve an authentication token (JWT) for the user. The result/response of this endpoint can be accessed from the onUserLogin(ServerResponseObject response) callback. You must extract the “access_token” value and use it to set the CoreLibrary JWT field.

Below is the code you have to add in onUserLogin(ServerResponseObject response) upon successful response from the server:

if(response.getResponseBody()!=null && (!response.getResponseBody().isEmpty()))
{
    try
    {
        JSONObject loginJson = new JSONObject(response.getResponseBody());

        if(!loginJson.isNull("access_token"))
        {
            String strJwtToken = loginJson.getString("access_token");
            CoreLibrary.getInstance().setUserJWT(strJwtToken);
        }
    }
    catch (Exception e)
    {
        e.printStackTrace();
    }
}

Login User (syndicated)

In the ACTV8me ecosystem, a syndicated user is a user that has been register using an external authentication provider. In this case, the ACTV8me backend "trusts" that the client has successfully authenticated the user, and allows the login of such user using a unique identifier.

// Create and init UserPii
    UserPii user = new UserPii();

    user.setLogin_method(LoginMethods.SYNDICATED);
    user.setExternal_id("ABCD-12345"); // sample external id

    CoreLibrary.getInstance().login(user, null); // no password needed

📘

The external ID can be any string that you consider unique for the user. The ACTV8me backend does not perform validation of this ID against the auth provider.

Get User Account Details

After a successful user login, you can get user account details by calling the following method:

CoreLibrary.getInstance().getUserDetails();

The SDK handles the authorization requirement for this request by using the user access token that you set earlier using the "CoreLibrary.getInstance().setUserJWT()" method.

Below is the resulting code snippet (including the user authentication):

boolean isAllDone = false;
if(response.getResponseBody()!=null && (!response.getResponseBody().isEmpty()))
{
    try
    {
        JSONObject loginJson = new JSONObject(response.getResponseBody());

        if(!loginJson.isNull("access_token"))
        {
            String strJwtToken = loginJson.getString("access_token");
            CoreLibrary.getInstance().setUserJWT(strJwtToken);
            isAllDone =true;

        }
    }
    catch (Exception e)
    {
        e.printStackTrace();
    }

    if(isAllDone)
    {
       CoreLibrary.getInstance().getUserDetails();
    }
    else
    {
        Toast.makeText(this, “Unknown Error”, Toast.LENGTH_SHORT).show();
    }
}

In order to be notified by the user details endpoint result, the Activity needs to implement the interface me.actv8.core.util.Actv8CallbackInterface.GetUserDetailsListener. This interface has one abstract method: 

void onUserDetailsResponse(ServerResponseObject response);

In the above method, ServerResponseObject is the actual response from the server.

In order to use GetUserDetailsListener**, you need to add the line below to the onCreate()* method of the Activity implementing it:

CoreLibrary.getInstance().addGetUserDetailsListener(this);

and the line below to the onDestroy() method of the Activity implementing it:

CoreLibrary.getInstance().removeGetUserDetailsListener(this);

Upon successful execution of the CoreLibrary.getInstance().getUserDetails() method, you’ll get partial user details (see "me.actv8.core.UserDetails" class for more details) as a response to the onUserDetailsResponse() callback method. To parse the response, your onUserDetailsResponse() callback implementatioin should resemble this:

Actv8User actv8User // Declare this variable globally

boolean isAllDone = false;
try
{
    JSONObject detailJson = new JSONObject(response.getResponseBody());
    Gson gson = new Gson();

    UserDetails userDetails = gson.fromJson(detailJson.toString(), UserDetails.class);

    if (userDetails!=null)
    {
        actv8User = new Actv8User();
        actv8User.setTopDetails(userDetails);

        isAllDone = true;
    }
}
catch (JSONException e)
{
    e.printStackTrace();
}

if(isAllDone)
{
     CoreLibrary.getInstance().getUserProfile(""+userDetails.getId());
}else
{
    Toast.makeText(this, “Error, please try again later”, Toast.LENGTH_SHORT).show();
}

Get User profile data

Using the userId property retrieved from the user account details (above), you may retrieve user profile data by calling the CoreLibrary.getInstance().getUserProfile(String userId) method.

Below is the complete code around the onUserDetailsResponse() callback method:

Actv8User actv8User // Declare this variable globally

boolean isAllDone = false;
try
{
    JSONObject detailJson = new JSONObject(response.getResponseBody());
    Gson gson = new Gson();

    UserDetails userDetails = gson.fromJson(detailJson.toString(), UserDetails.class);

    if (userDetails!=null)
    {
        actv8User = new Actv8User();
        actv8User.setTopDetails(userDetails);

        isAllDone = true;
    }
}
catch (JSONException e)
{
    e.printStackTrace();
}

if(isAllDone)
{
     CoreLibrary.getInstance().getUserProfile(""+userDetails.getId());
}
else
{
    Toast.makeText(this, “Error, please try again later”, Toast.LENGTH_SHORT).show();
}

In order to be notified by the user profile endpoint result, the Activity needs to implement the interface me.actv8.core.util.Actv8CallbackInterface.GetUserProfileListener. This interface has one abstract method:

void onUserProfileResponse(ServerResponseObject response);

In above method, ServerResponseObject is the actual response from the server.

In order to use the GetUserProfileListener, you need to add the following line to the onCreate() method of the Activity implementing it:

CoreLibrary.getInstance().addGetUserProfileListener(this);

and the line below to the onDestroy() method of the Activity implementing it:

CoreLibrary.getInstance().removeGetUserProfileListener(this);

Upon successful execution of the CoreLibrary.getInstance().getUserProfile() endpoint, you’ll get the user profile details (see “me.actv8.core.UserPii” class for more details) in response to the onUserProfileResponse() callback method. You may parse this response and set the current user using the CoreLibrary.getInstance().setCurrentUser(actv8User) method.

Finally your “onUserProfileResponse()” callback method should look like this:

boolean isAllDone = false;

try
{
    JSONObject profileJson = new JSONObject(response.getResponseBody());

    Gson gson = new Gson();

    UserPii userPii = gson.fromJson(profileJson.toString(), UserPii.class);

    if (userPii!=null)
    {
        isAllDone =true;
        actv8User.setPii(userPii);
        actv8User.getPii().setPassword(passwordEditText.getText().toString());
        actv8User.setPassword(passwordEditText.getText().toString());
        actv8User.getPii().setLogin_method(actv8User.getTopDetails().getLogin_method());
        CoreLibrary.getInstance().setCurrentUser(actv8User);
    }
}
catch (Exception e)
{
    e.printStackTrace();
}

if (isAllDone)
{
    // Write your code to switch to your MainActivity/HomeScreen Here
}
else
{
    Toast.makeText(this, getResources().getString(R.string.unknown_error), Toast.LENGTH_SHORT).show();
}

Update User

SDK provides the following method to update the logged-in user info (DOB and Gender)--

CoreLibrary.getInstance().updateUser(UpdateUserObject user);

Here UpdateUserObject is a model class defined in me.actv8.core.objects package.

🚧

SDK allows only to update DOB and Gender

In order to be notified by the update user result, the Activity needs to implement the
interface 

me.actv8.core.util.Actv8CallbackInterface.OnUserUpdateListener.

The OnUserUpdateListener interface has one abstract method:

void onOnUserUpdate(ServerResponseObject response);

In the method above ServerResponseObject is the actual response from the server.

In order to use the OnUserUpdateListener, you need to add the following line to the onCreate()
method of the Activity implementing it:

CoreLibrary.getInstance().addOnUserUpdateListener(this);

and the line below to the onDestroy() method of the Activity implementing it:

CoreLibrary.getInstance().removeOnUserUpdateListener(this);

Logout User

The SDK also provides the CoreLibrary.getInstance().logout() method to logout an authenticated user from the system. In order to be notified by the Logout result, the Activity needs to implement the
interface me.actv8.core.util.Actv8CallbackInterface.OnUserLogoutListener. This interface has one abstract method:

void onUserLogout(ServerResponseObject response);

In the method above ServerResponseObject is the actual response from the server.

In order to use the OnUserLogoutListener, you need to add the following line to the onCreate()
method of the Activity implementing it:

CoreLibrary.getInstance().addOnUserLogoutListener(this);

and line below to the onDestroy() method of activity implementing it:

CoreLibrary.getInstance().removeOnUserLogoutListener(this);

Trigger Detection

Listening for Triggers

The CoreLibrary allows the application to access ACTV8me trigger protocol.

Within the ACTV8me ecosystem, a trigger is a component capable of emitting a signal that can be detected and decoded by the SDK. Using an event-driven approach, a client can perform an action (or set of actions) upon detection of a trigger signal. For example, a common use case is to send a content delivery request to the backend servers after detecting and decoding an audio trigger.

The Activity registers to the Trigger event with the interface me.actv8.core.util.Actv8CallbackInterface.OfferDetectionListener.

Audio Trigger Detection

In order to start the audio detection service, you will need to call below method in onCreate() method of your MainActivity or in any other activity where you want to listen for the offers:

Actv8SoundLib.getInstance().startListening(this, String strhsSetttingUrl);

Notice: The strhsSetttingUrl is provided by the ACTV8me support team upon SDK registration.

📘

To help reduce battery drainage, the ACTV8me backend provides the capability to attach a schedule to the audio listening service. This feature can be controlled from the ACTV8me Dashboard or via an API call. By default, the schedule is disabled, which results in the service to be always ON. When enabled, the SDK retrieves the schedule from the application settings and handles all the logic for enabling/disabling the audio service in the background.

Also, to stop the audio detection service, you should add the code below in the onDestroy() method of the same activity:

Actv8SoundLib.getInstance().stopListening(this);

📘

To "catch" an offer from a trigger, the user of the Application doesn’t need to be logged in (anonymous user). However, certain features of the platform (i.e. digital wallet) are only available for signed in users.

The “OfferDetectionListener” interface allows the SDK to notify the user upon a successful delivery of content, using the method onOfferDetected(ServerResponseObject response, ArrayList ContentObject content). Information about the content is available through the ServerResponseObject (Actual response from the server) and ArrayList ContentObject (List of content items)

@Override
public void onOfferDetected(ServerResponseObject response, ArrayList ContentObject content)
{
    <YOUR CODE HERE>
}

In order to use the OfferDetectionListner, you need to add the following line to the onCreate() method of the implementing Activity:

CoreLibrary.getInstance().addOfferDetectedListener(this);

and the line below to the onDestroy() method of the implementing activity:

CoreLibrary.getInstance().removeOfferDetectedListener(this);

ACTV8me Background Service Listening

The process of listening for audio trigger signals can be controlled from within the Application by the methods starListening() & stopListening(). This will listen in the background as long as it is active. The start and stop methods can be used as follows:

Actv8SoundLib.getInstance().startListening(Context context, String hsSettingsUrl);
Actv8SoundLib.getInstance().stopListening(Context context);

Notice: The hsSetttingUrl is provided by the ACTV8me support team upon SDK registration.

The service requires the activity to exist in order to run so it is recommended to call stopListening() in the Activity’s onDestroy() method to avoid any crashes.

Notes

The audio service needs exclusive access to the microphone in order to run. This means that if a different process is using the microphone then the service will not be properly started. Conversely if the service is running and a different process tries to access the microphone it will not be able to.

Geofence Trigger Detection

Overview

The ACTV8me Android SDK has the ability to detect geofences as triggers. Upon detection, the SDK uses the unique identifier to requets content from the delivery service.

In order to start geofence detection, you may use the following method call:

startGeofencingActv8BluetoothLib.getInstance().startGeofencing(this);

To stop the geofence service, simply call the method below:

Actv8BluetoothLib.getInstance().stopGeofencing();

Notes:

  • Attempting to call these methods before initializing the SDK will result in an error.
  • Your license should determine if you can use the geofence triggers. Please contact [email protected] if you have any issues with this feature.

Digital Wallet

The ACTV8me platform provides all the backend services you need to offer your users a digital wallet within your app. Every successful delivery of content to a user (or device) results in an entry on the ACTV8me database linking the user (or device) to such content, which becomes a wallet item.

Note:
In order to access the digital wallet, the user needs to be authenticated.

Retrieve wallet items

The user wallet is no more than a collection of content linked to the authenticated user upon successful delivery. Such conllection can be retrieved by calling the following method:

CoreLibrary.getInstance().getUserContent();

In order to be notified by the user content result, the Activity needs to implement the interface
me.actv8.core.util.Actv8CallbackInterface.OnGetUserContentListener. This interface has one abstract method:

void onGetUserContent(ServerResponseObject response, List ContentObject  contentList);

In the above method ServerResponseObject response is the actual response from the server and List ContentObject contains list of content items assigned to the user.

In order to use the OnGetUserContentListener, you need to add the following line to the onCreate() method of the Activity implementing it:

CoreLibrary.getInstance().addOnGetUserContentListener(this);

and the line below to the onDestroy() method of the activity implementing it:

CoreLibrary.getInstance().removeOnGetUserContentListener(this);

Delete Content

The following method allows for the deletion of content items from the wallet of an authenticated user:

CoreLibrary.getInstance().deleteContent(ContentObject content);

In order to be notified by the delete content result, the Activity needs to implement the
interface 

me.actv8.core.util.Actv8CallbackInterface.OnDeleteContentListener.

The OnDeleteContentListener interface has one abstract method:

void onDeleteContent(ServerResponseObject response);

In the method above, ServerResponseObject is the actual response from the server. In order to use theOnDeleteContentListener, you need to add the following line to the onCreate() method of the Activity implementing it:

CoreLibrary.getInstance().addOnDeleteContentListener(this);

and the line below to the onDestroy() method of the activity implementing it:

CoreLibrary.getInstance().removeOnDeleteContentListener(this);

Content Status

Based on how the user with interacts with the delivered content (i.e. offer), you may want to change the status of the content as follows:

0 => UNSEEN: the offer has been delivered to the user, but no interaction has been detected
1 => VIEWED: the user has revealed the information about the content
2 => SAVED / ACCEPT: the user has devided to save the content to the digital walletr
3 => DECLINED: the user is not interested in saving the content to the digital wallet 
4 => REDEEMED_IN_STORE: the user has interacted with the offer with an intent to redeem in store
5 => REDEEMED_ONLINE: the user has interacted with the offer with an intent to redeem online
6 => DELETED: the user has deleted the offer from the digital wallet

Using the values described above, you can use the following method to change the status of the content:

CoreLibrary.getInstance().updateContentStatus(ContentObject content);

Note:
ContentObject is a model class defined in me.actv8.core.objects package.

In order to be notified by the update status result, the Activity needs to implement the interface

me.actv8.core.util.Actv8CallbackInterface.OnUpdateContentStatusListener. This interfacte has interface has one abstract method:

void onUpdateContentStatus(ServerResponseObject response);

In method above ServerResponseObject is the actual response from the server.

In order to use the OnUpdateContentStatusListner, you need to add the following line to the onCreate() method of the Activity implementing it:

CoreLibrary.getInstance().addOnUpdateContentStatusListener(this);

and the line below to the onDestroy() method of the Activity implementing it:

CoreLibrary.getInstance().removeOnUpdateContentStatusListener(this);

Content Status Update for Anonymous (not logged-in) User

Although the Digital Wallet requires a user to be authenticated, updating the status of a content is still possible for an annonymous (not signed-in) user by using the following method:

CoreLibrary.getInstance().updateAnonymousContent(ContentObjectcontent);

Note:
ContentObject is a model class defined in me.actv8.core.objects package.

In order to be notified by the update status result, the Activity needs to implement the interface me.actv8.core.util.Actv8CallbackInterface.AnonymousStatusUpdateListener. This interface has has one abstract method:

void onAnonymousUpdateStatusResponse(ServerResponseObject response);

In the method above, ServerResponseObject is the actual response from the server.

In order to use the OnUpdateContentStatusListner, you need to add the following line to the onCreate() method of the implementing Activity:

CoreLibrary.getInstance().addAnonymousStatusUpdateListener(this);

and line below to the onDestroy() method of the activity implementing it.

CoreLibrary.getInstance().removeAnonymousStatusUpdateListener (this);

Shutdown

Below method should be called in “onDestroy()” method of your MainActivity.

CoreLibrary.getInstance().shutdown();

This method should be called when the application is being destroyed. This is important to retain DeviceObject and UserObject from the last login.

Updated almost 4 years ago