jtproximity_flutter

Description:

jtproximity flutter

Jointag Proximity Wrapper for Flutter (Android / iOS) #
Table of Contents #

Requirements
Installation
Usage
Permissions and hardware requirements
Tracking user identifier

Advertising ID and Installation ID
External User ID


Data Tags

sendTag
sendTags


Customizing the notifications (Android)
Receive custom events
Programmatically Disable Advertising
GDPR Consent

Enabling the Consent Flow support
Using Consent Management Platform
Implementing a Custom Consent Flow



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 #
Add flutter_jointag in pubspec.yaml
dependencies:
flutter_jointag: ^1.0.0
copied to clipboard
run
flutter pub get
copied to clipboard
Usage #
Initialization #

Android
Create a Java class in the source root (the same place as MainActivity):

public class Application extends FlutterApplication {
@Override
public void onCreate() {
super.onCreate();
FlutterJointagPlugin.Initialize(this, YOUR_APIKEY, YOUR_SECRET );
}
}
copied to clipboard
Then, change the application->name in the AndroidManifest.xml to

iOS
Initialize the plugin in AppDelegate

SwiftJTProximityFlutterPlugin.initializeWithOptions(launchOptions: launchOptions, apiKey: YOUR_APIKEY, apiSecret: YOUR_SECRET)
copied to clipboard
<application
android:name=".Application"
copied to clipboard
Permissions and hardware requirements #
You need to ask the user for ACCESS_FINE_LOCATION and ACCESS_COARSE_LOCATION for android 6.0 or later.
You also need ACCESS_BACKGROUND_LOCATION for android 10.0 or later.
Ex. (using the permission_handler and device_info plugins)
//Location
var statusL = await Permission.location.status;
if (statusL.isUndetermined || statusL.isDenied) {
if (Platform.isIOS) {
PermissionStatus permissionStatus = await Permission.location.request();
//do something if the permission is granted/not granted
} else if (Platform.isAndroid) {
AndroidDeviceInfo androidInfo = await deviceInfo.androidInfo;
if (androidInfo.version.sdkInt <= 29) {
//ask location always
PermissionStatus permissionStatus = await Permission.location.request();
//do something if the permission is granted/not granted
} else {
//from android 30 ask for normal location and open the settings page
PermissionStatus permissionStatus = await Permission.location.request();
//do something if the permission is granted/not granted
openAppSettings();
}
}
}

//Notification
var statusN = await Permission.notification.status;
if (statusN.isUndetermined || statusN.isDenied) {
PermissionStatus permissionStatus = await Permission.notification.request();
//do something if the permission is granted/not granted
}

//Tracking
await FlutterProximityPlugin.requestTrackingAuthorization;
copied to clipboard
After having requested the permissions to the user and the user has granted the required permissions, the monitoring process must be resumed by calling:
FlutterJointag.checkPendingPermissions;
copied to clipboard
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:
await FlutterProximityPlugin.getInstallationId;
copied to clipboard
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
await FlutterProximityPlugin.setExternalUserId("SOME_ID");
// Unset
await FlutterProximityPlugin.setExternalUserId(null);
copied to clipboard
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.
await FlutterProximityPlugin.sendTag("key1","value");
// -> { "key1" : "value" }
await FlutterProximityPlugin.sendTag("key1",1);
// -> { "key1" : "value", "key2" : 1 }
await FlutterProximityPlugin.sendTag("key1",true);
// -> { "key1" : "value", "key2" : 1, "key3" : true }
await FlutterProximityPlugin.sendTag("key1",false);
// -> { "key1" : "value", "key2" : 1, "key3" : false }
await FlutterProximityPlugin.sendTag("key2",null);
// -> { "key1" : "value", "key3" : false }
copied to clipboard
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.
Map tags = { "key1" : "value", "key2" : 1, "key3" : true };
await FlutterProximityPlugin.sendTags(tags);
// -> { "key1" : "value", "key2" : 1, "key3" : true }

Map tags = { "key1" : "value", "key2" : null, "key3" : false };
await FlutterProximityPlugin.sendTags(tags);
// -> { "key1" : "value", "key3" : false }
copied to clipboard
Customizing the notifications (Android) #
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][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.
// Define an Handler
void customHandler(dynamic payload) {
showDialog(
context: this.context,
builder: (BuildContext context) {
return AlertDialog(
title: Text("payload"),
content: Text(payload),
);
});
}

// Set
FlutterProximityPlugin.addCustomActionListeners(customHandler, "SOME_ID");
// Unset
FlutterProximityPlugin.removeCustomActionListeners("SOME_ID");
copied to clipboard
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
await FlutterProximityPlugin.setAdvertisingDisabled;
// enable advertising delivery
await FlutterProximityPlugin.setAdvertisingEnabled;
copied to clipboard


Note: disabling the advertising 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
await FlutterProximityPlugin.enabledCmp static method.

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
await FlutterProximityPlugin.getProfilingConsent;
await FlutterProximityPlugin.enableProfilingConsent;
await FlutterProximityPlugin.disableProfilingConsent;

// Retrieve or update the manual user monitoring consent
await FlutterProximityPlugin.getMonitoringConsent;
await FlutterProximityPlugin.enableMonitoringConsent;
await FlutterProximityPlugin.disableMonitoringConsent;

// Retrieve or update the manual user advertising consent
await FlutterProximityPlugin.getAdvertisingConsent;
await FlutterProximityPlugin.enableAdvertisingConsent;
await FlutterProximityPlugin.disableAdvertisingConsent;

// Retrieve or update the manual user advanced tracking consent
await FlutterProximityPlugin.getAdvancedTrackingConsent;
await FlutterProximityPlugin.enableAdvancedTrackingConsent;
await FlutterProximityPlugin.disableAdvancedTrackingConsent;
copied to clipboard


⚠️ 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.