Flutter Tenjin Plugin

Summary

The Tenjin Flutter Plugin allows users to track events and installs in their iOS/Android apps. To learn more about Tenjin and our product offering, please visit https://www.tenjin.com.

Plugin Integration

1. Add the dependency to the pubspec.yaml file in your project:

dependencies:
  tenjin_plugin: '^1.0.0'

2. Install the plugin by running the command below in the terminal, in your project's root directory:

$ flutter pub get

Android ProGuard Settings:

-keep class com.tenjin.** { *; }
-keep public class com.google.android.gms.ads.identifier.** { *; }
-keep public class com.google.android.gms.common.** { *; }
-keep public class com.android.installreferrer.** { *; }
-keep class * extends java.util.ListResourceBundle {
    protected Object[][] getContents();
}
-keepattributes *Annotation*

Notes:

On iOS: For AppTrackingTransparency, be sure to update your project .plist file and add NSUserTrackingUsageDescription along with the text message you want to display to users. This library is only available in iOS 14.0+. For further information on this, you can check our iOS documentation

On Android: You will need to add Google's Install Referrer Library to your gradle dependencies. If you haven’t already installed the Google Play Services you also need to add it

dependencies {
  classpath("com.android.installreferrer:installreferrer:1.1.2")
  classpath("com.google.android.gms:play-services-analytics:17.0.0")
}

Manifest requirements:

<manifest>
  ...
  <uses-permission android:name="android.permission.INTERNET"></uses-permission>
  <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"></uses-permission>
  ...
</manifest>

Usage

Initialization

Get your API_KEY from your Tenjin Organization tab. You can initialize Tenjin with the function

TenjinSDK.instance.init(apiKey: '<API-KEY>');

You can verify if the integration is working through our Live Test Device Data Tool. Add your advertising_id or IDFA/GAID to the list of test devices. You can find this under Support -> Test Devices. Go to the SDK Live page and send a test events from your app. You should see a live event come in:

GDPR compliance

As part of GDPR compliance, with Tenjin's SDK you can opt-in, opt-out devices/users, or select which specific device-related params to opt-in or opt-out. OptOut() will not send any API requests to Tenjin and we will not process any events.

TenjinSDK.instance.init(apiKey: '<API-KEY>');

bool userOptIn = checkOptInValue();

if (userOptIn) {
    TenjinSDK.instance.optIn();
} else {
    TenjinSDK.instance.optOut();
}

TenjinSDK.instance.connect();

To opt-in/opt-out specific device-related parameters, you can use the OptInParams() or OptOutParams(). OptInParams() will only send device-related parameters that are specified. OptOutParams() will send all device-related parameters except ones that are specified. Please note that we require at least ip_address, advertising_id, developer_device_id, limit_ad_tracking, referrer (Android), and iad (iOS) to properly track devices in Tenjin's system. If you plan on using Google, you will also need to add: platform, os_version, locale, device_model, and build_id.

If you want to only get specific device-related parameters, use OptInParams(). In example below, we will only these device-related parameters: ip_address, advertising_id, developer_device_id, limit_ad_tracking, referrer, and iad:

TenjinSDK.instance.init(apiKey: '<API-KEY>');

List<String> optInParams = {"ip_address", "advertising_id", "developer_device_id", "limit_ad_tracking", "referrer", "iad"};
TenjinSDK.instance.optInParams(optInParams);

TenjinSDK.instance.connect();

If you want to send ALL parameters except specfic device-related parameters, use OptOutParams(). In example below, we will send ALL device-related parameters except:

TenjinSDK.instance.init(apiKey: '<API-KEY>');

List<String> optOutParams = {"locale", "timezone", "build_id"};
TenjinSDK.instance.optOutParams(optOutParams);

TenjinSDK.instance.connect();

SetGoogleDMAParameters

If you already have a CMP integrated, Google DMA parameters will be automatically collected by the Tenjin SDK. There’s nothing to implement in the Tenjin SDK if you have a CMP integrated. If you want to override your CMP, or simply want to build your own consent mechanisms, you can use the following:

TenjinSDK.instance.setGoogleDMAParameters(adPersonalization, adUserData);

To explicitly manage the collection of Google DMA parameters, you have the flexibility to opt in or opt out at any time. While the default setting is to opt in, you can easily adjust your preferences using the OptInGoogleDMA or OptOutGoogleDMA methods, ensuring full control over your data privacy settings:

TenjinSDK.instance.optOutGoogleDMA();
TenjinSDK.instance.optInGoogleDMA();

Device-Related Parameters

Param	Description	Reference
ip_address	IP Address
advertising_id	Device Advertising ID	Android
limit_ad_tracking	limit ad tracking enabled	Android
platform	platform	Android
referrer	Google Play Install Referrer	Android
os_version	operating system version	Android
device	device name	Android
device_manufacturer	device manufactuer	Android
device_model	device model	Android
device_brand	device brand	Android
device_product	device product	Android
carrier	phone carrier	Android
connection_type	cellular or wifi	Android
screen_width	device screen width	Android
screen_height	device screen height	Android
os_version_release	operating system version	Android
build_id	build ID	Android
locale	device locale	Android
country	locale country	Android
timezone	timezone	Android

Purchase Event

To understand user revenue and purchase behavior, developers can send transaction events to Tenjin. There are two ways to send transaction events to Tenjin.

Validate receipts

Tenjin can validate transaction receipts for you.

Example:

TenjinSDK.instance.transactionWithReceipt(
  ...
);

TenjinSDK.instance.transaction(
  ...
);

You can verify if the IAP validation is working through our Live Test Device Data Tool. You should see a live event come in:

Custom Event

NOTE: DO NOT SEND CUSTOM EVENTS BEFORE THE INITIALIZATION connect() event (above). The initialization event must come before any custom events are sent.

IMPORTANT: Limit custom event names to less than 80 characters. Do not exceed 500 unique custom event names.

You can use the Tenjin SDK to pass a custom event: eventWithName(String name).

The custom interactions with your app can be tied to level cost from each acquisition source that you use through Tenjin's service. Here is an example of usage:

//Integrate a custom event with a distinct name - ie. swiping right on the screen
TenjinSDK.instance.eventWithName("swipe_right");

Passing custom events with integer values:

To pass a custom event with an integer value: eventWithNameAndValue(String name, String value) or eventWithNameAndValue(String name, int value).

Passing an integer value with an event's name allows marketers to sum up and track averages of the values passed for that metric in the Tenjin dashboard. If you plan to use DataVault, these values can be used to derive additional metrics that can be useful.

TenjinSDK.instance.eventWithNameAndValue("item", 100);

Using the example above, the Tenjin dashboard will sum and average the values for all events with the name item.

Keep in mind that this event will not work if the value passed is not an integer.

Deep Links

---

Tenjin supports the ability to direct users to a specific part of your app after a new attributed install via Tenjin's campaign tracking URLs. You can utilize the getDeeplink method and callback to access the deferred deeplink through the data object. To test you can follow the instructions found here

TenjinSDK.instance.setRewardCallback = (bool clickedTenjinLink,
        bool isFirstSession, Map<String, String> data) {
      if (isFirstSession) {
        if (clickedTenjinLink) {
          if (data.containsKey(TenjinSDK.DEEPLINK_URL)) {
            // use the deferred_deeplink_url to direct the user to a specific part of your app
          }
        }
      }
    };

Below are the parameters, if available, that are returned in the deferred deeplink callback:

Parameter	Description
advertising_id	Advertising ID of the device
ad_network	Ad network of the campaign
campaign_id	Tenjin campaign ID
campaign_name	Tenjin campaign name
site_id	Site ID of source app
referrer	The referrer params from the app store
deferred_deeplink_url	The deferred deep-link of the campaign
clickedTenjinLink	Boolean representing if the device was tracked by Tenjin
isFirstSession	Boolean representing if this is the first session for the device

You can also use the v1.7.1+ SDK for handling post-install logic by checking the isFirstSession param. For example, if you have a paid app, you can register your paid app install in the following way:

TenjinSDK.instance.init(apiKey: '<API-KEY>');
TenjinSDK.instance.setRewardCallback = (bool clickedTenjinLink,
        bool isFirstSession, Map<String, String> data) {
      if (isFirstSession) {
          // send paid app price and revenue to Tenjin
      }
    };

App Subversion parameter for A/B Testing (requires DataVault)

If you are running A/B tests and want to report the differences, we can append a numeric value to your app version using the appendAppSubversion method. For example, if your app version 1.0.1, and set appendAppSubversion: @8888, it will report as 1.0.1.8888.

This data will appear within DataVault where you will be able to run reports using the app subversion values.

TenjinSDK.instance.init(apiKey: '<API-KEY>');
TenjinSDK.instance.appendAppSubversion(8888);
TenjinSDK.instance.connect();

Other methods available

Customer User ID

TenjinSDK.setCustomerUserId(userId)

TenjinSDK.getCustomerUserId()

GetAnalyticsInstallationId

You can get the analytics id which is generated randomly and saved in the local storage of the device.

String? analyticsId = await TenjinSDK.instance.getAnalyticsInstallationId();

Send AdMob impression (ILRD)

TenjinSDK.eventAdImpressionAdMob(json)

Send AppLovin impression (ILRD)

TenjinSDK.eventAdImpressionAppLovin(json)

Send HyperBid impression (ILRD)

TenjinSDK.eventAdImpressionHyperBid(json)

Send IronSource impression (ILRD)

TenjinSDK.eventAdImpressionIronSource(json)

Send TopOn impression (ILRD)

TenjinSDK.eventAdImpressionTopOn(json)

Send TradPlus impression (ILRD)

TenjinSDK.eventAdImpressionTradPlus(json)
TenjinSDK.eventAdImpressionTradPlusAdInfo(adInfo)

Support

If you have any issues with the plugin integration or usage, please contact us to [email protected]