Android

Table of Contents

1. Requirements

2. Installation

   1. Add the Maven repository

   2. Add the library

   3. Other dependencies

3. Usage

   1. Initialization

      1. Automatic Initialization

      2. Manual Initialization

   2. Permissions and hardware requirements

   3. Tracking user identifier

   4. Data Tags

   5. Customizing the notifications

   6. Receive custom events

   7. Programmatically Disable Advertising

   8. GDPR Consent

      1. Enabling the Consent Flow support

      2. Using Consent Management Platform

      3. Implementing a Custom Consent Flow

   9. Background Jobs ID

This library allows you to integrate Jointag Proximity into your Android app.

Requirements

Minimum API level: 16 (Android 4.1)

Note: to use functionalities that rely on BLE, the minimum API level is 18 (Android 4.3). If the device API level is between 16 and 17 the SDK won't be able to access BLE and therefore it will be not possible to obtain data from BLE devices.

Installation

For the installation of the SDK please refer to the technical documentation on Next14 github repositoty: https://github.com/jointag/JTProximitySDK-Android#user-content-installation

Usage

For technical information on the SDK usage please refer to the technical documentation on Next14 github repositoty: https://github.com/jointag/JTProximitySDK-Android#user-content-usage

Tracking user identifier

Advertising ID and Installation ID

The SDK associates each tracked request with the advertisingId. If the advertisingId is not available due to a user permission denial, the device can be identified by the installationId. The installationId is a randomly generated UUID created during the first initialization that hence identifies a specific installation of the SDK for that application. If the app containing the SDK is uninstalled and then installed again the installationId will be a different one. You can retrieve the installationId after the initialization of the SDK anywhere in your code with the following line:

ProximitySDK.getInstance().getInstallationId();

External User ID

The externalUserId is an identifier you set to pair a unique user identifier of your choice with our installationId. Tipically this identifier must be set after a user has signed in to your application, and must be removed after the same user decides to sign out of you application.

You can choose any string of 255 characters or less as externalUserId.

Your externalUserId can be paired with multiple installationId, for example if the same user uses your app on multiple devices, or if the same user uninstalled and installed your app multiple times.

On the other hand, the same installationId can be associated with one and only one externalUserId, usually the last one sent.

For example, you can use the user record id of your database or your CRM, or the hash of an email address, or a third party platform identifier.

Use the setExternalUserId method to add your unique external user ids:

// Set
ProximitySDK.getInstance().setExternalUserId("SOME ID");
// Unset
ProximitySDK.getInstance().setExternalUserId(null);

Data Tags

Tags are custom key-value pairs of string, number, boolean or null type, that can be sent to our server through the SDK methods and that allow you a more effective campaigns targeting, or to receive personalized analysis based on the characteristics of your users.

Tags can be set or unset (with a null value) using the following methods:

sendTag

The sendTag method allow to set or unset a single tag at a time.

The method can be called multiple times. When sending different keys, its effects are cumulative. If the same key is used, the last value overwrites the previous ones.

{ "key1" : "value" } ProximitySDK.getInstance().sendTag("key2", 1); // -> { "key1" : "value", "key2" : 1 } ProximitySDK.getInstance().sendTag("key3", true); // -> { "key1" : "value", "key2" : 1, "key3" : true } ProximitySDK.getInstance().sendTag("key3", false); // -> { "key1" : "value", "key2" : 1, "key3" : false } ProximitySDK.getInstance().sendTag("key2", null); // -> { "key1" : "value", "key3" : false } ">

ProximitySDK.getInstance().sendTag("key1", "value");
// -> { "key1" : "value" }
ProximitySDK.getInstance().sendTag("key2", 1);
// -> { "key1" : "value", "key2" : 1 }
ProximitySDK.getInstance().sendTag("key3", true);
// -> { "key1" : "value", "key2" : 1, "key3" : true }
ProximitySDK.getInstance().sendTag("key3", false);
// -> { "key1" : "value", "key2" : 1, "key3" : false }
ProximitySDK.getInstance().sendTag("key2", null);
// -> { "key1" : "value", "key3" : false }

sendTags

The sendTags method allow to set or unset a multiple tags at a time.

The method can be called multiple times. When sending different keys, its effects are cumulative. If the same key is used, the last value overwrites the previous ones.

{ "key1" : "value", "key2" : 1, "key3" : true } Map tags = new HashMap<>(); tags.put("key2", null); tags.put("key3", false); ProximitySDK.getInstance().sendTags(tags); // -> { "key1" : "value", "key3" : false } ">

Map<String,Object> tags = new HashMap<>();
tags.put("key1", "value");
tags.put("key2", 1);
tags.put("key3", true);
ProximitySDK.getInstance().sendTags(tags);
// -> { "key1" : "value", "key2" : 1, "key3" : true }

Map<String,Object> tags = new HashMap<>();
tags.put("key2", null);
tags.put("key3", false);
ProximitySDK.getInstance().sendTags(tags);
// -> { "key1" : "value", "key3" : false }

Customizing the notifications

It is possibile to to customize the icon and color of the advertising notifications.

In order to customize the icon, include in your project a drawable named ic_stat_jointag_default.

We recommend using Android Asset Studio to quickly and easily generate small icons with the correct settings.

If you prefer to create your own icons, make sure to generate the icon for the following densities:

• mdpi

• hdpi

• xhdpi

• xxhdpi

• xxxhdpi

In order to customize the color for all notifications, include in your project a color resource named jointag_notification_color. The default icon color is #2576BC

⚠️ Attention: with some versions of the android build tool a duplicate resource error may arise during the resource merging phase of the build. In this case it is sufficient to include the new drawable resources using a version qualifier. Eg:

• drawable-hdpi-v7/ic_stat_jointag_default.png

• drawable-mdpi-v7/ic_stat_jointag_default.png

• drawable-xhdpi-v7/ic_stat_jointag_default.png

• drawable-xxhdpi-v7/ic_stat_jointag_default.png

• drawable-xxxhdpi-v7/ic_stat_jointag_default.png

Receive custom events

You can receive custom advertising events (if configured in the backend) to integrate application-specific features by registering a CustomActionListener object using the addCustomActionListener method of ProximitySDK.

When the application user interacts with a custom-action notification, the onCustomAction method is invoked by passing a payload string object.

Since the CustomActionListener object is retained by ProximitySDK, remember to remove the listener when the owning instance is being deallocated to avoid unwanted retaining or NullPointerException. It is therefore good practice to use a long-life object as CustomActionListener, such as the Application object.

Programmatically Disable Advertising

It is possible to programmatically disable/enable the advertising delivery by setting the SDK's advertisingEnabled property to false. It is useful for example to disable the delivery of advertising for specific users of the application. In that case, simply change the property as soon as the user sign in or out of the application. The default value for the property is true.

// disable advertising delivery
ProximitySDK.getInstance().setAdvertisingEnabled(false);
// enable advertising delivery
ProximitySDK.getInstance().setAdvertisingEnabled(true);

Note: disabling the advertising via setAdvertisingEnabled(false) has always effect regardless of any other control method (ie: the user consent)

GDPR Consent

As a publisher, you should implement a user consent flow either manually or using a Consent Management Platform (CMP) and request for vendor and purpose consents as outlined in IAB Europe’s Mobile In-App CMP API v2.0: Transparency & Consent Framework.

Enabling the Consent Flow support

To ensure that the SDK support the handling of user-consent preferences when a IAB-compatible CMP library is present, you must enable the feature through the ProximitySDK.enabledCmp() static method or the com.jointag.proximity.CMP_ENABLED meta-data in your AndroidManifest.xml file.

If you are following the Manual Initialization procedure, this method must be called before calling the library init method to guarantee an error-free process.

Using Consent Management Platform

When configuring a third-party CMP to use with the Jointag Proximity SDK, the following requirements must be met:

• In order to enable the delivery of advertising, a custom publisher purpose must be configured in the CMP, and it must be the first custom purpose.

Implementing a Custom Consent Flow

If you need to handle the user consent flow manually without the use of a IAB-compatible CMP library, or if the CMP you are using do not allow the customization of custom publisher purpose, it is possibile to do so by implementing an in-app consent screen and interacting with the SDK using the following methods:

// Retrieve or update the manual user profiling consent
ProximitySDK.getInstance().getManualConsent(ManualConsent.Profiling);
ProximitySDK.getInstance().setManualConsent(ManualConsent.Profiling, true);

// Retrieve or update the manual user monitoring consent
ProximitySDK.getInstance().getManualConsent(ManualConsent.Monitoring);
ProximitySDK.getInstance().setManualConsent(ManualConsent.Monitoring, true);

// Retrieve or update the manual user advertising consent
ProximitySDK.getInstance().getManualConsent(ManualConsent.Advertising);
ProximitySDK.getInstance().setManualConsent(ManualConsent.Advertising, true);

// Retrieve or update the manual user advanced tracking consent
ProximitySDK.getInstance().getManualConsent(ManualConsent.AdvancedTracking);
ProximitySDK.getInstance().setManualConsent(ManualConsent.AdvancedTracking, true);

⚠️ Attention: When the manual consent method is used in the presence of a CMP library, the choices made using the above methods take precedence over the choices made by the user in the CMP library screen.

Background Jobs ID

On Android 5.0 or later, the SDK use Job Services to perform scheduled tasks. Since the JobScheduler need to identify each jobs with a unique ID, the SDK gives each job an identifier starting from a predefined constant (182734746).

If for any reason this identifier should collide with any one used by the application or by another library, it is possible to change the starting value for the SDK job identifiers by calling Scheduler.setBaseJobId before the ProximitySDK.init call.

import com.jointag.proximity.scheduler.Scheduler;

...
int newJobID = 123456;
Scheduler.setBaseJobId(newJobID);

ProximitySDK.init(this, "YOUR_API_KEY", "YOUR_API_SECRET");
...