Unity
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
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 both iOS and Android.
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 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.
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
public void TapContentShown(string placementTag)
{
Debug.Log("Survey Content Opened");
}
public void TapContentDismissed(string placementTag)
{
Debug.Log("Survey Content Dismissed");
}
Error callback setup
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
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.