Unity

info

Notes on apps in test mode! If your app is in test mode, you MUST use a test user. These are defined in "Test Devices" on the dashboard.

Integration

External Dependency Manager from Google

Before importing TapResearchSDK.unitypackage make sure the latest EDM is imported into your Unity Download external-dependency-manager-latest.unitypackage Assets -> Import Package -> Custom Package

Note: If you already have EDM installed, skip this step or use this opportunity to update to the latest EDM.

Import all files

info

Previously Installed Android? If you have previously integrated for Android, please remove any existing TapResearch aar files before importing the new package.

Assets/Plugins/Android/tapsdk.aar
Assets/Plugins/Android/*unitybridge.aar
Assets/TapResearchSDK/Plugins/Android/tapsdk.aar
Assets/TapResearchSDK/Plugins/Android/*unitybridge.aar

Installation

You can download the latest version of the TapResearch Unity SDK on GitHub.

You can follow our simple C# script TapResearchExample.cs as an example or proceed with the steps below:

Integrate .unitypackage

Inside the TapResearchSDK directory, you will find TapResearchSDK.unitypackage. You can import the package by selecting Assets > Import Package > Custom Package... through the Unity menu.

The TapResearch SDK includes the binaries for iOS and uses EDM to fetch Android binaries.

Android Setup

Android EDM Settings

We recommend using the Default settings, EXCEPT Explode AARs.

Assets -> External Dependency Manager -> Android Resolver -> Settings

Uncheck Explode AARs (no longer recommended by Google)

After importing EDM and TapResearchSDK.unitypackage a dialog might pop-up asking to ENABLE AUTO-RESOLVE dependencies. Be sure to click ENABLE. We recommend auto-resolve because it makes integration much easier.

Android API Levels

Build Settings -> Player Settings -> Other Settings, set Minimum API Level 24.

Target API Level to HIGHEST INSTALLED (33 or higher recommended).

Android Proguard Rules

Copy and paste our proguard rules to your existing proguard file located at:

Assets/Plugins/Android/proguard-user.txt

If you do not have this file, please create it with our proguard rules.

Unity 2020 or earlier

If you use Unity 2020 or earlier, please uncheck all Minify options including Debug, Release, and R8 under Player Settings -> Publishing Settings

iOS Project Setup

Frameworks

The TapResearchSDK includes a post-process script that runs after compilation to add required frameworks and linker flags to the generated Xcode project for iOS.

Callbacks

SDK Ready callback example

This function will be called when the SDK is ready to show content.

It is a good time to update TapResearch with initial user attributes.

See more on user attributes here.

User attributes are used to target specific users with content (ex: an offer). They can be set at any time and the most recent values received will be used when determining which content to show.

User attributes are passed as a dictionary of key-value pairs.

note

User attributes prefixed with tapresearch_ are reserved for internal use. Please do not use this prefix for user attributes as doing so will result in an error

The keys must be strings and the values must be one of:

• String
• Float
• Integer

If you want to use a date, please stringify an ISO8601 date or use a timestamp.

You can send user attributes as soon as the SDK is ready. This is done by calling SendUserAttributes with a Dictionary of attributes.

We suggest sending as many attributes as you think that you'll want to target on for surveys, special awards, etc.

public void TapSdkReady()
{
    Debug.Log("TapResearchSDK ready, going to send user attributes");

    Dictionary<string, object> userAttributes = new Dictionary<string, object>();
    userAttributes["some_string"] = "a string value";
    userAttributes["some_number"] = "12";
    userAttributes["another_number"] = 12;
    userAttributes["boolean"] = "true";
    userAttributes.Add("another_string", "it's another string!");
    DateTime now = DateTime.UtcNow;
    string iso8601String = now.ToString("o");
    userAttributes["iso8601_date"] = iso8601String;

    TapResearchSDK.SendUserAttributes(userAttributes);
}

Rewards callback info

The SDK will check if the user has unredeemed rewards in the following events:

• On SDK initialization
• When the user exits TapResearch

The TapResearchRewardReceived interface is the reward listener that will handle the new rewards that the player earned in a session.

The reward information will be encapsulated in the TRReward object with the following methods:

Method name	Type	Description
TransactionIdentifier	String	The reward unique identifier
CurrencyName	String	The virtual currency name
PlacementIdentifier	String	The placement identifier that started the session identifier
PlacementTag	String	The placement tag that started the session identifier
RewardAmount	int	The reward amount in virtual currency. The value will automatically be converted to your virtual currency based on the exchange rate you specified in the app settings.
PayoutEvent	int	The action that the user was rewarded for. 0 - Profile Complete, 3 - Survey Complete.

Rewards callback example

This function will receive the rewards that the user earned in a session. It is an array of TRReward objects and must be defined prior to calling Configure().

private void TapResearchRewardsReceived(TRReward[] rewards)
{
    foreach (TRReward reward in rewards)
    {
        Debug.Log("Tap Rewards: You've earned " + reward.RewardAmount + " " + reward.CurrencyName + ". " + reward.TransactionIdentifier);
    }
}

Content shown / dismissed callback setup

These are required but do not need to do anything

    public void TapContentShown(string placementTag)
    {
        Debug.Log("Survey Content Opened");
    }

    public void TapContentDismissed(string placementTag)
    {
        Debug.Log("Survey Content Dismissed");
    }

Error callback setup

This is required but does not need to do anything

Any error received from the TapResearch SDK will be passed back to this function

    public void TapResearchDidError(string errorMessage)
    {
        Debug.Log("TapResearch Error: " + errorMessage);
    }

Quick Question response callback

danger

The Quick Question response callback feature is currently in beta!

    public void TapResearchQQResponseReceived(TRPayloadObject payload) {
        Debug.Log("QQ Response Received: ") + payload);
    }

Initialization

Initialize the TapResearchSDK as early as possible. Please note that the Configure() method only needs to be called once on app launch, make sure to call DontDestroyOnLoad() in the C# code for the class that implements the SDK's callbacks.

You must declare your callback functions prior to calling Configure().

Caveat: Initialize the TapResearchSDK as early as possible once user identifier is known. Do NOT use an anonymized user identifier.

Your iOS and Android apps have different API tokens. Use pre-processor directives so Unity knows which API token to use when you build your app.

private static string tapAPIToken;
private static string tapPlayerUserId = "YOUR_UNIQUE_USER_ID";
private static string placementTag = "home-screen";

    void Awake()
    {
        DontDestroyOnLoad(this); // Don't destroy this object on scene change

#if UNITY_ANDROID
        tapAPIToken = "90d0d66d0213cf0245254e3d3b222e92";  // Public Test Android, replace with your own API token
#elif UNITY_IPHONE
        tapAPIToken = "ed51703ae058f16bd196a81f9fc1bfcb";  // Public Test iOS, replace with your own API token
#endif

        TapResearchSDK.TapContentShown = TapContentShown;
        TapResearchSDK.TapContentDismissed = TapContentDismissed;
        TapResearchSDK.TapResearchRewardReceived = TapResearchRewardsReceived;
        TapResearchSDK.TapResearchDidError = TapResearchDidError;
        TapResearchSDK.TapResearchSdkReady =  TapSdkReady;

        TapResearchSDK.Configure(tapAPIToken, tapPlayerUserId);
    }

Passing User Attributes with Configure

You can send a User Attributes dictionary when initializing the SDK.

    Dictionary<string, object> userAttributes = new Dictionary<string, object>();
    userAttributes["some_string"] = "a string value";
    userAttributes["some_number"] = "12";
    userAttributes["another_number"] = 12;
    userAttributes["boolean"] = true;
    userAttributes.Add("another_string", "it's another string!");

    TapResearchSDK.ConfigureWithUserAttributes(tapAPIToken, tapPlayerUserId, userAttributes, true);

Configure with user attributes takes the following parameters: an API token string, player identifier string, user attributes dictionary and a boolean indicating wether the user attributes replace existing attributes or are an update to previously-set attributes.

info

If user attributes are known at SDK initialization, it is preferable to use ConfigureWithUserAttributes compared to Configure. This will result in quicker load times for targeted content.

Displaying a placement

Wrapping in CanShowContentForPlacement is optional but recommended. It will check if the placement is ready to be shown before attempting to show it. If the placement is not ready, it will return false and you can try again later.

public void showSurveyContent()
{
    if (TapResearchSDK.CanShowContentForPlacement(placementTag)) //DefaultTest Placement
    {
        TapResearchSDK.ShowContentForPlacement(placementTag); //DefaultTest Placement
    }
}

Passing custom parameters

Parameters can only be ascii characters, Unicode is not supported.

ShowContentForPlacement(string placementTag, Dictionary<string, string> customParameters);

public void showSurveyContentWithParameters()
{
    if (TapResearchSDK.CanShowContentForPlacement(placementTag)) //CustomParam Placement
    {
        Dictionary<string, string> customParameters = new Dictionary<string,string>(); //Parameters
        customParameters["player_attribute"] = "my-vip";
        customParameters["data_value"] = "integer";
        customParameters["another_number"] = 12;
        customParameters.Add("another_string", "it's another string!");

        TapResearchSDK.ShowContentForPlacement(placementTag, customParameters);
    }
}

Setting user attributes

User Attributes can only be ascii characters, Unicode is not supported.

SendUserAttributes( Dictionary<string, object> userAttributes, bool clearPreviousAttributes);

Pass a dictionary and a boolean flag indicating if existing attributes should be cleared or not when setting, or updating, with new user attributes.

    Dictionary<string, object> userAttributes = new Dictionary<string, object>();
    userAttributes["some_string"] = "a string value";
    userAttributes["some_number"] = "12";
    userAttributes["another_number"] = 12;
    userAttributes["boolean"] = true;
    userAttributes.Add("another_string", "it's another string!");

    TapResearchSDK.SendUserAttributes(userAttributes, true);

Setting a new player/user identifier

A new user identifier can be set by passing a user identifier string to UpdateCurrentUser():

    TapResearchSDK.UpdateCurrentUser(new_user_identifier);

Checking if the SDK is ready

The SDK lets the app know it is ready using a callback. Using this callback is described in the SDK Ready callback example above.

You can also check if the SDK is ready using the IsReady() call:

if (TapResearchSDK.IsReady()) {
    ...
}

Screen Orientation for Landscape Applications:

TapResearch works better in portrait mode. Using Unity Player Settings to disable Portrait orientation may result in problems rendering some surveys.

TapResearch Surveys and Quick Questions

To make sure that TapResearch surveys display in portrait mode when you have locked your game in landscape mode set the Screen.orientation to ScreenOrientation.Portrait. Use co-routines or scene-loads to make sure it is in effect before opening any TapResearch content. We recommend switching into portrait orientation if you have locked your game to landscape.

TapResearch Banners & Interstitials

Banners and interstitials can work in any orientation, however when tapped they will go on to show surveys. For placements starting with a banner or interstitial we recommend switching to Screen.orientation to ScreenOrientation.AutoRotation with landscape left, right and portrait enabled for auto-rotation:

Screen.autorotateToPortrait = true;
Screen.autorotateToLandscapeLeft = true;
Screen.autorotateToLandscapeRight = true;

Unity example project

An example project for Unity can be found in GitHub. This example shows how to integrate the TapResearchSDK package and how orientation can be managed.

Unity example project orientation handling

We have included a simple orientation changer class TROrientationChanger.cs in the example project that illustrates how to change orientation.

When our example starts we set (lock) to landscape orientation using

Screen.orientation = ScreenOrientation.LandscapeLeft;

View in context

When we are ready to show TapResearch content we use the included example orientation changer to change to portrait orientation:

    orientationChanger.SetPortrait(OnOrientationChangedToPortrait);

View in context

In the completion handler for SetPortrait we show the placement:

private void OnOrientationChangedToPortrait()
{
    TapResearchSDK.ShowContentForPlacement(placementTag); 
}

View in context

When the user dismisses the surveys we do the reverse to return to landscape orientation:

    orientationChanger.SetLandscapeLeft(OnOrientationChangedToLandscapeLeft);

View in context