Unity

What you'll do

1. Install the SDK
2. Set up reward callbacks
3. Initialize the SDK
4. Display a placement

Later sections cover platform setup, user attributes, the user identifier, and more.

Testing? Your app starts in test mode, so you'll need a test device to see content while you build.

Installation

Download Source code (zip) for your SDK version from GitHub releases, then extract the archive.

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

External Dependency Manager

Before importing TapResearchSDK.unitypackage, install an External Dependency Manager (EDM):

• Unity 2022.3 and later: install Unity's External Dependency Manager from the Package Manager.
• Older Unity versions: download Google's external-dependency-manager-latest.unitypackage and import it with 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

Integrate .unitypackage

The extracted folder contains 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

targetSdk 35+

If your app's targetSdk is 35 or higher, you will need to use version 3.5.3 or higher. Android 15 introduced a change that will cut off the top title bar of the Survey Wall.

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.

Build post process script

The Unity package includes a BuildPostprocessoriOS.cs script that performs some necessary modifications to the Xcode project that is generated when exporting a build from the Unity editor.

The script extracts and embeds TapResearchSDK.xcframework and configures the generated Xcode project.

Integration

Add using TapResearch; to any script that calls the SDK.

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 User attributes and targeting for more.

User attributes are used to target specific users with content (ex: an offer). The most recent values received are used when determining which content to show.

See Send user attributes for supported values and update options.

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	string	The action the user was rewarded for; see payout event values.

Setting the rewards callback

• You can set different reward callbacks in different scenes, when setting different callbacks for different scenes then the best practice is to set a scene's callback to null before loading a new scene. When setting a new reward callback the old one is replaced.
• You can set one, and make sure that the object it is attached to is non-destructible so that it survives scene loads (see https://docs.unity3d.com/ScriptReference/Object.DontDestroyOnLoad.html).

Rewards callback example

This function will receive the rewards that the user earned in a session as an array of TRReward objects. You can set this before or after 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(TRError error)
    {
        Debug.Log("TapResearch Error: " + error.ErrorDescription);
    }

Quick Question response callback

New to Quick Questions? See Quick Questions for what they are and the response payload.

Setting the Quick Question response callback

• You can set different Quick Question response callbacks in different scenes, when setting different callbacks for different scenes then the best practice is to set a scene's callback to null before loading a new scene. When setting a new Quick Question response callback the old one is replaced.
• You can set one, and make sure that the object it is attached to is non-destructible so that it survives scene loads (see https://docs.unity3d.com/ScriptReference/Object.DontDestroyOnLoad.html).

This function will receive a Quick Question response object. You can set this before or after calling Configure().

    private void TapQQResponseReceived(TRQQDataPayload payload) {
        Debug.Log("TapResearchExample: TRQQDataPayload received! placement: " + payload.PlacementTag + " userIdentifier: " + payload.UserIdentifier);
    }

Initialization

Initialize the TapResearchSDK as early as possible once unique user identifier is known. 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.

Note

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.

Tip

The user identifier passed through initialization must be unique! Only initialize once you are able to provide a unique identifier. Re-using the same user identifier is not supported and will prevent your users from accessing our service.

private static string tapAPIToken;
private static string userIdentifier = "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.TapResearchDidError = TapResearchDidError;
        TapResearchSDK.TapResearchSdkReady =  TapSdkReady;

        TapResearchSDK.Configure(tapAPIToken, userIdentifier);

        // Set your reward handler when you are ready to receive the rewards
        TapResearchSDK.TapResearchRewardReceived = TapResearchRewardsReceived;

        // Set your quick question handler when you are ready to receive quick question result data
        TapResearchSDK.TapResearchQQResponseReceived = TapQQResponseReceived;
    }

Displaying a placement

Wrapping in CanShowContent 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.CanShowContent(placementTag)) //DefaultTest Placement
    {
        TapResearchSDK.ShowContentForPlacement(placementTag); //DefaultTest Placement
    }
}

Passing custom parameters

Note

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

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

public void showSurveyContentWithParameters()
{
    if (TapResearchSDK.CanShowContent(placementTag)) //CustomParam Placement
    {
        Dictionary<string, object> customParameters = new Dictionary<string, object>(); //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);
    }
}

Send user attributes

Note

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

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

Attribute names must be strings and must not begin with tapresearch_, which is reserved for TapResearch. Use string or numeric values for targeting. For booleans, send "true"/"false" or 0/1 instead of native booleans.

Set clearPreviousAttributes to false to merge new values with existing attributes, or true to replace the attributes you previously sent.

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

Send 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, userIdentifier, userAttributes, true);

Configure with user attributes takes the following parameters: an API token string, player identifier string, user attributes dictionary and a boolean indicating whether 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 SendUserAttributes. This will result in quicker load times for targeted content.

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()) {
	...
}

Getting placement details

Get placement details by calling:

TRPlacementDetails TapResearchSDK.GetPlacementDetails(string placementTag)

TRPlacementDetails is defined as:

	public struct TRPlacementDetails
	{
		public readonly string Name;
		public readonly string ContentType;
		public readonly string CurrencyName;
		public readonly bool   IsSale;
		public readonly string SaleType;
		public readonly string SaleEndDate;
		public readonly double SaleMultiplier;
		public readonly string SaleDisplayName;
		public readonly string SaleTag;
		public readonly TRBonusBarProgress BonusBarProgress;
	}

    public struct TRBonusBarProgress
    {
		public readonly bool              IsActive;
		public readonly int               CurrentCompletes;
		public readonly string            BonusWindowEndAt;
		public readonly TRBonusTier[]     BonusTiers;
		public readonly Nullable<TRError> Error;
    }

    public struct TRBonusTier
    {
        public readonly int    TierNumber;
		public readonly int    CompletesNeeded;
		public readonly int    RewardAmount;
		public readonly string Status;
	}

Granting boosts

Call GrantBoost with a configured User Boosts tag. The result is delivered to the TapResearchGrantBoostResponse delegate:

// Set the handler before granting, for example alongside your other delegates
TapResearchSDK.TapResearchGrantBoostResponse = TapGrantBoostResponse;

TapResearchSDK.GrantBoost("YOUR_BOOST_TAG");

void TapGrantBoostResponse(TRGrantBoostResponse response)
{
    if (response.Success)
    {
        // Boost granted
    }
    else
    {
        Debug.Log("Grant boost failed for " + response.BoostTag + ": " + response.Error.ErrorDescription);
    }
}

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 projects

Example projects for Unity can be found in GitHub. The examples show how to integrate the TapResearchSDK package and how orientation can be managed.

Full feature-set Unity example

In the full feature-set example you can set your API tokens in two ways: setting variable in C# (See source), or using the Unity editor.

If you would like to set your API token using the editor:

1. Open the example;
2. Open the TapResearchTestScene scene from the TapResearchSDKExample folder in the assets list;
3. Select Canvas in the hierarchy panel;
4. In the Inspector panel for Canvas scroll to the OS-specific token values and enter your API tokens.

If you prefer to set the API token value in C#:

1. Open TapResearchExample.cs in your favorite editor
2. Set your API tokens in the Awake() function before TapResearchSDK.Configure(tapAPIToken, tapPlayerUserId); on Line 57.

Wall Unity example

This example contains a single simple scene and C# source file in Assets/TapResearchWallDemo that shows how to present TapResearch content and respond to show, dismiss and rewards callbacks.

Native Survey Tiles Unity example

This example shows how to integrate the Native Survey Tiles feature. It contains 2 scenes:

1. TapResearchTestScene: Starts the TapResearchSDK, shows how to check if a Native Survey Tiles placement has surveys;
2. WallPreviewScene: Shows how to use the TRSurvey objects returned by getting surveys using TapResearchSDK.GetSurveysForPlacement().

Unity example project orientation handling

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

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

Screen.orientation = ScreenOrientation.LandscapeLeft;

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

	orientationChanger.SetPortrait(OnOrientationChangedToPortrait);

In the completion handler for SetPortrait we show the placement:

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

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

	orientationChanger.SetLandscapeLeft(OnOrientationChangedToLandscapeLeft);

Need help?

Email developers@tapresearch.com.

Stay updated: watch the TapResearch Unity SDK on GitHub to get notified about new releases.