Unity

danger

While we are in beta, you cannot use v3.1/v3.2 of the SDK until you are enabled for it. Please reach out to developers@tapresearch.com to be enabled. If you try to use this sdk with an older app token, you will receive an error.

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.

Installation

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

Integration

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

TapResearch only supports LTS Release 2021.3.30f1 and above. Please see Unity LTS support for more information.

Download the SDK

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

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 both iOS and Android.

Android Implementation:

3.1.0-beta+/3.2.0-beta+ requires you to import to following dependencies. Please see the Android docs for additional details

implementation 'androidx.lifecycle:lifecycle-process:2.6.1'
implementation 'androidx.core:core-ktx:1.10.1'
implementation 'org.jetbrains.kotlinx:kotlinx-serialization-json:1.3.3'
implementation 'com.google.android.gms:play-services-ads-identifier:18.0.1'
implementation(platform("org.jetbrains.kotlin:kotlin-bom:1.8.0"))
// used for custom params
implementation 'com.google.code.gson:gson:2.8.0'

iOS Project Setup

Frameworks

The TapResearchSDK includes a post-process script that runs after compilation to add required frameworks and linker flags 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().

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.

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.

```csharp
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);

Screen Orientation:

To force the application to render in landscape mode only, it would be better to use the following screen orientation guide instead of disabling the portrait orientation in the player settings. TapResearch works better in portrait mode so using the player settings may result in some problems rendering the surveys.