tenjin_sdk

A Flutter plugin to Tenjin SDK.


License
Other

Documentation

Flutter Tenjin Plugin

Pub Version

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'
  1. 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();
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.

Dashboard

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.


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

Get attribution info

Map<String, dynamic>? attributionInfo = await TenjinSDK.instance.getAttributionInfo();  

Customer User ID

TenjinSDK.setCustomerUserId(userId)
TenjinSDK.getCustomerUserId()

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)

Support

If you have any issues with the plugin integration or usage, please contact us to support@tenjin.com