Unity SDK

SDK Installation


Package Installation

  • Download the latest version of Airbridge Unity SDK
  • Go to Assets > Import Package > Custom Package ... and import the downloaded package file.
  • Once the package is installed, AB180 tab appears on the menu

Project Setup

  • Click AB180 > Airbridge Settings menu and will see the following screen

๐Ÿšง

Press Update iOS App Setting or Update Android Manifest to apply changes

๐Ÿšง

If you want to customize or merge the Android Manifest file, refer to Project > Plugins > Airbridge > Android > AndroidManifest.xml file

App Information Setup

Enter App Name (Unique ID) and App SDK Token information to App Name and App Token fields of AB180 > Airbridge Settings at the menu

This information can be checked on the Airbridge dashboard โ†’ Settings โ†’ Tokens tab

Initialization

For Airbridge Unity SDK, no additional initialization is required but in special cases, each platform may require a separate migration work

Testing

You can check your events into Raw Data โ†’ App Real-time Log page on the dashboard after run your application

๐Ÿšง

Real-time logs may have a delay of up to 5 minutes

Deep Link Setup


Dashboard Setup

The deep link dashboard settings for each iOS and Android platform are variable as follows

  • iOS Deep Link Dashboard Setup Guide
  • Android Deep Link Dashboard Setup Guide

Project Setup

iOS Deep Link Setup

Enter iOS URI Scheme information to iOS URI Scheme field of AB180 > Airbridge Settings at the menu

This information can be checked on the Airbridge dashboard โ†’ Tracking Link โ†’ Deep Link tab

Android Deep Link Setup

Enter Android URI Scheme information to Android URI Scheme field of AB180 > Airbridge Settings at the menu

This information can be checked on the Airbridge dashboard โ†’ Tracking Link โ†’ Deep Link tab

Custom Domain Setup

When you create a tracking link from the Airbridge dashboard, deeplink.page or abr.ge type of link is available but customized URLs such as go.my_company.com/abcd can be used as tracking link in order to improve the branding and click rate(CTR) of the tracking link as follows.

  1. Please set the custom domain you want to use as following guide

  2. Enter the custom domain address set previously to Custom Domain field of AB180 > Airbridge Settings at the menu

Callback Setup

Following method is requiring the class name for receiving deep link data that user clicks on

private void Awake()
{
    AirbridgeUnity.SetDeeplinkCallback("AirbridgeManager");
}

The class will get deep link URL with the following method

using UnityEngine;

public class AirbridgeManager : MonoBehaviour
{ 
  private void Awake() {
    Airbridge.SetDeeplinkCallback("AirbridgeManager");
  }
  
  // Method will call by Airbridge when deeplink detected
  private void OnTrackingLinkResponse(string url)
  {

  }
}

๐Ÿ“˜

Airbridge Unity is internally using UnitySendMessage method

Testing

After the deep link configuration of the Airbridge Unity SDK is completed, you can check whether it has been correctly setup through the following links

  • YOUR_APP_URI_SCHEME://

After deep link configuration and verification is completed, you can check on the Airbridge dashboard โ†’ Row Data โ†’ App Real-time Log tab

User Setup


User Identifier Setup

To measure the contribution of fragmented users between Web and App, Airbridge collects the following user identifier information

  • User Email : Email address
  • User Phone : Phone number
  • User ID : Unique User ID (The Web and App must match 1:1 with the user's specific ID values)
  • User Alias : Identifiers that can represent users(e.g. loyalty program ID, affiliate integrated ID, etc)

๐Ÿ“˜

The user's email and phone numbers are automatically HASH(SHA256)

In the Airbridge Unity SDK, you can set the user identifier in the following ways

Dictionary<string, string> alias = new Dictionary<string, string>();
AirbridgeUser user = new AirbridgeUser();
user.SetId(UserId);
user.SetEmail(Email);
user.SetPhoneNumber(Phone);
user.SetAlias(alias);
AirbridgeUnity.SetUser(user);
  • User Alias maximum number is up to 10
  • User Alias key must be String type and length is up to 128
  • User Alias key should satisfy ^[a-z_][a-z0-9_]*$ regular expression
  • User Alias value must be String type and length is up to 1024

Once you setup user identifier, all events will be forward with that identity information

๐Ÿšง

The user identifier set can be reset or overwritten through user events

User Attribute Setup

Additional user attribute data can be improve accuracy of Multi-Touch Attribute(MTA) analysis, internal data analysis and linking thrd-party solutions

Dictionary<string, object> attrs = new Dictionary<string, object>();
AirbridgeUser user = new AirbridgeUser();
user.SetAttributes(attrs);
AirbridgeUnity.SetUser(user);
  • User Attribute maximum number is up to 100
  • User Attribute key must be String type and up to 128
  • User Attribute key should satisfy ^[a-z_][a-z0-9_]*$ regular expression
  • User Attribute value must be Primitive type or String type and up to 1024 for String

๐Ÿšง

The user attribute set can be reset or overwritten through user events

Testing

User information set in Airbridge Unity SDK can be checked on the Airbridge Dashboard โ†’ Row Data โ†’ App Real-time Log tab

Event Setup


All the events that calls by Airbridge Unity SDK has following fields can be contains

  • Event Category : Name of event Required (String)
  • Event Action : Event attribute 1 (String)
  • Event Label : Event attribute 2 (String)
  • Event Value : Event attribute 3 (Float)
  • Event Custom Attributes : Additional fields that can represent the event (Map<String, Object>)
  • Event Semantic Attributes : Additional semantic fields that can represent the event (Semantic Attributes Class)

User Events

For convenience, the Airbridge Unity SDK provides the following user events

  • Sign Up
Dictionary<string, string> alias = new Dictionary<string, string>();
AirbridgeUser user = new AirbridgeUser();
user.SetId(UserId);
user.SetEmail(Email);
user.SetPhoneNumber(Phone);
user.SetAlias(alias);
AirbridgeUnity.SetUser(user);

AirbridgeEvent @event = new AirbridgeEvent(Airbridge.Constants.CATEGORY.SIGN_UP);
AirbridgeUnity.TrackEvent(@event);
  • Sign In
Dictionary<string, string> alias = new Dictionary<string, string>();
AirbridgeUser user = new AirbridgeUser();
user.SetId(UserId);
user.SetEmail(Email);
user.SetPhoneNumber(Phone);
user.SetAlias(alias);
AirbridgeUnity.SetUser(user);

AirbridgeEvent @event = new AirbridgeEvent(Airbridge.Constants.CATEGORY.SIGN_IN);
AirbridgeUnity.TrackEvent(@event);
  • Sign Out
AirbridgeEvent @event = new AirbridgeEvent(Airbridge.Constants.CATEGORY.SIGN_OUT);
AirbridgeUnity.TrackEvent(@event);
AirbridgeUnity.ExpireUser();

๐Ÿšง

All user identifier and property values will disappear after sign out called

E-Commerce Events

For convenience, Airbridge Unity SDK provides e-commerce events with the following product classes

Airbridge.Ecommerce.Product cocacola = new Airbridge.Ecommerce.Product();
cocacola.SetId("beverage_1");
cocacola.SetName("Coca Cola");
cocacola.SetPrice(1.25f);
cocacola.SetCurrency("USD");
cocacola.SetQuantity(1);
cocacola.SetPosition(0);
  • Home Screen View
AirbridgeEvent @event = new AirbridgeEvent(Airbridge.Constants.CATEGORY.VIEW_HOME);
AirbridgeUnity.TrackEvent(@event);
  • Search Results View
List<Airbridge.Ecommerce.Product> beverages = new List<Airbridge.Ecommerce.Product>();
Airbridge.Ecommerce.Product cocacola = new Airbridge.Ecommerce.Product();
cocacola.SetId("beverage_1");
cocacola.SetName("Coca Cola");
cocacola.SetPrice(1.25f);
cocacola.SetCurrency("USD");
cocacola.SetQuantity(1);
cocacola.SetPosition(0);
beverages.Add(cocacola);

Airbridge.Ecommerce.Product fanta = new Airbridge.Ecommerce.Product();
fanta.SetId("beverage_2");
fanta.SetName("Fanta");
fanta.SetPrice(10.99f);
fanta.SetCurrency("USD");
fanta.SetQuantity(1);
fanta.SetPosition(1);
beverages.Add(fanta);

AirbridgeEvent @event = new AirbridgeEvent(Airbridge.Constants.CATEGORY.VIEW_SEARCH_RESULT);
@event.SetQuery("SELECT * FROM beverages");
@event.SetProducts(beverages.ToArray());
@event.SetTotalValue(12.24f);
AirbridgeUnity.TrackEvent(@event);
  • Product List View
List<Airbridge.Ecommerce.Product> beverages = new List<Airbridge.Ecommerce.Product>();
Airbridge.Ecommerce.Product cocacola = new Airbridge.Ecommerce.Product();
cocacola.SetId("beverage_1");
cocacola.SetName("Coca Cola");
cocacola.SetPrice(1.25f);
cocacola.SetCurrency("USD");
cocacola.SetQuantity(1);
cocacola.SetPosition(0);
beverages.Add(cocacola);

Airbridge.Ecommerce.Product fanta = new Airbridge.Ecommerce.Product();
fanta.SetId("beverage_3");
fanta.SetName("Fanta");
fanta.SetPrice(10.99f);
fanta.SetCurrency("USD");
fanta.SetQuantity(1);
fanta.SetPosition(2);
beverages.Add(fanta);

AirbridgeEvent @event = new AirbridgeEvent(Airbridge.Constants.CATEGORY.VIEW_PRODUCT_LIST);
@event.SetProductListId("beverage_list_0");
@event.SetProducts(beverages.ToArray());
@event.SetTotalValue(12.24f);
AirbridgeUnity.TrackEvent(@event);
  • Product Details View
Airbridge.Ecommerce.Product cocacola = new Airbridge.Ecommerce.Product();
cocacola.SetId("beverage_1");
cocacola.SetName("Coca Cola");
cocacola.SetPrice(1.25f);
cocacola.SetCurrency("USD");
cocacola.SetQuantity(1);
cocacola.SetPosition(0);

AirbridgeEvent @event = new AirbridgeEvent(Airbridge.Constants.CATEGORY.VIEW_PRODUCT_DETAILS);
@event.SetProducts(cocacola);
AirbridgeUnity.TrackEvent(@event);
  • Add To Cart
Airbridge.Ecommerce.Product cocacola = new Airbridge.Ecommerce.Product();
cocacola.SetId("beverage_1");
cocacola.SetName("Coca Cola");
cocacola.SetPrice(1.25f);
cocacola.SetCurrency("USD");
cocacola.SetQuantity(1);
cocacola.SetPosition(0);

AirbridgeEvent @event = new AirbridgeEvent(Airbridge.Constants.CATEGORY.ADD_TO_CART);
@event.SetProducts(cocacola);
@event.SetTotalValue(1.25f);
AirbridgeUnity.TrackEvent(@event);
  • Order Complete
List<Airbridge.Ecommerce.Product> beverages = new List<Airbridge.Ecommerce.Product>();
Airbridge.Ecommerce.Product cocacola = new Airbridge.Ecommerce.Product();
cocacola.SetId("beverage_1");
cocacola.SetName("Coca Cola");
cocacola.SetPrice(1.25f);
cocacola.SetCurrency("USD");
cocacola.SetQuantity(1);
cocacola.SetPosition(0);
beverages.Add(cocacola);

Airbridge.Ecommerce.Product fanta = new Airbridge.Ecommerce.Product();
fanta.SetId("beverage_3");
fanta.SetName("Fanta");
fanta.SetPrice(10.99f);
fanta.SetCurrency("USD");
fanta.SetQuantity(1);
fanta.SetPosition(2);
beverages.Add(fanta);

AirbridgeEvent @event = new AirbridgeEvent(Airbridge.Constants.CATEGORY.ORDER_COMPLETE);
@event.SetTransactionId("transaction_123");
@event.SetProducts(beverages.ToArray());
@event.SetInAppPurchased(true);
@event.SetTotalValue(12.24f);
AirbridgeUnity.TrackEvent(@event);

Customized Events

You can send an customized event in the following way from the Airbridge Unity SDK

AirbridgeEvent @event = new AirbridgeEvent("category");
@event.SetAction("action");
@event.SetLabel("label");
@event.SetValue(value);
@event.AddCustomAttribute("custom_key", "value");
@event.AddSemanticAttribute("query", "query_123");
AirbridgeUnity.TrackEvent(@event);

๐Ÿ“˜

To configure and deliver Semantic Attributes directly, please check this guide.

Testing

Event information sent from the Airbridge Unity SDK can be checked on the Airbridge dashboard โ†’ Row Data โ†’ App Real-time Log tab

Advanced Setup


User Identifier Hash Setup

If you want to send identity information without HASH(SHA256) for internal data analysis, you can stop automatic HASH(SHA256) through User Info Hash Enabled field of AB180 > Airbridge Settings at the menu

โ—๏ธ

The option required separate security measures must be taken internally because provides sensitive personal information such as User Email and User Phone

Session Timeout Setup

Airbridge Unity SDK does not send app open event again if the user relaunch the app within the Session Timeout Seconds field of AB180 > Airbridge Settings at the menu otherwise will transfer app open event when the user relaunch the app after that time

Personal Information Protection

This function is useful when collecting and transferring data with consent form customers for personal information protection, such as GDPR or CCPA

Data collection and transmission can be started explicitly using the Auto Start Tracking Enabled field of AB180 > Airbridge Settings at the menu

๐Ÿ“˜

When this feature is disabled, the following functions must be explicitly called for proper data collection

AirbridgeUnity.startTracking();

Track Airbridge Link Only

If it is difficult to see the performance of re-engagement through Airbridge at a glance due to too many deep link actions within the advertiser's app, Track Airbridge Link Only field of AB180 > Airbridge Settings can be used to filter only the results received through Airbridge deep link

If the setting is activated, the result of the deep link is measured only when the app is opened through a deep link that matches the conditions below

  • The app is opened through a airbridge.io link
  • The app is opened through a deeplink.page link
  • The app is opened through a Custom Domain Setup that registered on a dashboard
  • The app is opened through airbridge_referrer query contains link

Location Collection

Airbridge Unity SDK can collect user location information through Location Collection Enabled field of AB180 > Airbridge Settings at the menu

โ—๏ธ

Location information must be collected through legitimate purposes and ways

๐Ÿšง

The option only available on Android device and to collects location information, the following permission must be included into AndroidManifest.xml file

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

Facebook Deferred App Links

You can receive Facebook Deferred App Link from the Airbridge Unity SDK through the setting of the Facebook Deferred App Link Enabled field of AB180 > Airbridge Settings at the menu

๐Ÿšง

The Facebook SDK setting must be preceded in advance to use the feature.
See - https://developers.facebook.com/docs/unity/

App Tracking Transparency

According to the policy change in iOS 14, the user's consent must be obtained through the App Tracking Transparency setting to correctly collect IDFA information

On the Airbridge Unity SDK, the iOS Tracking Authorize Timeout Seconds field of AB180 > Airbridge Settings allows you to delay the installation event so that the correct IDFA is included in the installation event

Troubleshooting


Android

1. Airbridge Unity seems not initialize correctly

  • Airbridge Unity for Android is initialiing automatically through Content Provider. For proper initialization, the following Xml Tag must be correctly place in Project > Plugins > Android > AndroidManifest.xml.
<provider
    android:authorities="${applicationId}.co.ab180.airbridge.unity.AirbridgeContentProvider"
    android:name="co.ab180.airbridge.unity.AirbridgeContentProvider"
    android:exported="false" />

2. Using your own Custom Activity Class

  • Airbridge Unity uses Custom Activity that extended UnityPlayerActivity to get deep link data. If you are using your own Custom Activity class, please override the following codes inside your Custom Activity class
@Override
protected void onNewIntent(Intent intent) {
  super.onNewIntent(intent);
  setIntent(intent);
}

@Override
protected void onResume() {
  super.onResume();
  AirbridgeUnity.processDeeplinkData(getIntent());
}

3. Android Manifest file seems not merge properly

  • Android Manifest Merger that Airbridge Unity provided is simple component that merging between Project > Plugins > Android > AndroidManifest.xml and Project > Plugins > Airbridge > Android > AndroidManifest.xml file. The merger cannot be satisfy all user cases. In this situation, it has to create own AndroidManifest.xml file with reference to Project > Plugins > Airbridge > Android > AndroidManifest.xml file.

4. Missing 'package' key attribute on element package at ...

In addition to the Android 11 version of the Package Visibility, application should be properly informed by the <queries> inside manifest file which packages and interactions are carried out to properly interact with another applications.

Airbridge includes changes in Android SDK modules to comply with the policy and requires at least 5.6.4 version of Gradle and at least 3.6.0 version of Android Gradle Plugin to support the <queries> tag.

For information of which version of Gradle is included depending on the Unity version, visit this page.

If the Gradle version of the Unity you use is less than the 5.6.4 version of the Android Gradle Pluginversion is less than the 3.6.0 version, you can use the specific version through the following Unity settings.

- Unity 2020.1 or later

The following versions do not require further action because they already contain versions of 'Gradle' 5.6.4 and later and 'Android Gradle Plugin' 3.6.0 and later.

- Unity 2019.3 to 2019.4

๐Ÿ“˜

The following customization is supported only on Unity 2018.4 patch 24 and later.

  1. Go to the Gradle Build Tool page and download the version of 'Gradle' 5.6.4 or higher
  2. Go to Preferences > External Tools to uncheck Gradle Installed with Unity (recommended) and set the path to the downloaded Gradle file as follows
  1. Go to Project Settings > Player > Android Tab > Publishing Settings > Build and select all of the following options:

a. Custom Main Gradle Template
b. Custom Launcher Gradle Template

  1. Please change both of the following auto generated files as follows
  • Assets/Plugins/Android/mainTemplate.gradle
  • Assets/Plugins/Android/launcherTemplate.gradle
buildscript {
    repositories {
        google()
        jcenter()
    }
    dependencies {
        // Must be Android Gradle Plugin 3.6.0 or later. For a list of
        // compatible Gradle versions refer to:
        // https://developer.android.com/studio/releases/gradle-plugin
        classpath 'com.android.tools.build:gradle:3.6.0'
    }
}

allprojects {
   repositories {
      google()
      jcenter()
      flatDir {
        dirs 'libs'
      }
   }
}

- Unity 2019.1 to 2019.2

  1. Go to the Gradle Build Tool page and download the version of 'Gradle' 5.6.4 or higher
  2. Go to Preferences > External Tools to uncheck Gradle Installed with Unity (recommended) and set the path to the downloaded Gradle file as follows
  1. Go to Project Settings > Player > Android Tab > Publishing Settings > Build and select Custom Gradle Template option as follows
  1. Go to the auto generated Assets/Plugins/Android/MainTemplate.gradle file and make the following changes
buildscript {
    dependencies {
        // Must be Android Gradle Plugin 3.6.0 or later. For a list of
        // compatible Gradle versions refer to:
        // https://developer.android.com/studio/releases/gradle-plugin
        classpath 'com.android.tools.build:gradle:3.6.0'
    }
}

- Unity 2018.4

๐Ÿ“˜

The following customization is supported only on Unity 2018.4 patch 24 and later

  1. Go to the Gradle Build Tool page and download the version of 'Gradle' 5.6.4 or higher
  2. Go to Build Settings > Android and set Build System to Gradle to use the custom version as follows
  1. Go to Preferences > External Tools to uncheck Gradle Installed with Unity (recommended) and set the path to the downloaded Gradle file as follows
  1. Go to Project Settings > Player > Android Tab > Publishing Settings > Build and select Custom Gradle Template option as follows
  1. Go to the auto generated Assets/Plugins/Android/MainTemplate.gradle file and make the following changes
buildscript {
    dependencies {
        // Must be Android Gradle Plugin 3.6.0 or later. For a list of
        // compatible Gradle versions refer to:
        // https://developer.android.com/studio/releases/gradle-plugin
        classpath 'com.android.tools.build:gradle:3.6.0'
    }
}

- Unity 2018.3 or earlier

Gradle customizations are not supported on these versions of Unity and are not compatible with the necessary changes to support Android 11 (API level 30).

iOS

1. Using your own Custom AppController

  • Airbridge Unity SDK uses IMPL_APP_CONTROLLER_SUBCLASS to create a Custom AppController. If you are using your own Custom AppController, please add the following codes inside your Custom AppController
- (BOOL) application:(UIApplication*)application 
continueUserActivity:(NSUserActivity*)userActivity 
  restorationHandler:(void (^)(NSArray<id<UIUserActivityRestoring>>* _Nullable))restorationHandler 
{
    [AUAppDelegate.instance application:application 
                   continueUserActivity:userActivity 
                     restorationHandler:restorationHandler];

    return YES;
}
  • After that please remove Assets > Plugins > Airbridge > iOS > Delegate > AUAppController.mm file