Unity SDK

Version Compatibility

The latest SDK v2.1.1 isn't backward-compatible with v2.0.x. Please follow the upgrade section

Getting Started#

Create an app and grab your API Token.
Add a test device

Supported versions#

TapResearch only supports Unity v5.0 and above.

Download the SDK#

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

Integrate TapResearch#

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

Library Dependencies#

The SDK uses External Dependency Manager for Unity to integrate the native library dependencies. If the dependency manager is already installed on your app, you can remove the Dependency Manager files when importing the SDK. For the Android build, make sure the dependencies have been resolved by going to Assets => External Dependency Manager => Android Resolver => Resolve. For iOS, the plugin will add CocoaPods to the project and will import the dependencies in the Xcode project.

iOS Project Setup#

Ensure you have the following inside the Assets > Plugins > iOS folder:
- TapResearch.framework
- TRUnityBridge.mm

Frameworks#

The TapResearchSDK includes a post-process script that runs after compilation to add required frameworks and linker flags for iOS. If you're using a Windows machine to generate the Xcode project or if the script fails, you'll need to add the frameworks and set the linker flags manually.

Add the following frameworks to Target > Build Phases > Link Binary With Libraries:
- Foundation.framework
- UIKit.framework
- SystemConfiguration.framework
- MobileCoreServices.framework
- AdSupport.framework
- Security.framework

Linker Flags#

Select the build settings tab and type in Other Linker Flags in the search field.
Add the following flag.
- -ObjC

Android Project Setup#

Ensure you have the following inside the Assets > Plugins > Android folder:
- tapresearch.aar
- unitybridge.aar
- play-services-ads-lite-10.2.6.aar
- play-services-basement-10.2.6.aar

Initialize TapResearch#

Initialize the TapResearchSDK as early as possible. Please note that the Configure() method only needs to be called once on app launch. Also, 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.

using TapResearch;

#if UNITY_IOS
    const String ApiToken = "ios_api_token";
#elif UNITY_ANDROID
    const String ApiToken = "android_api_token";
#endif

public class MyMainController : MonoBehaviour {
    public void Awake()
    {
        TapResearchSDK.Configure(ApiToken);
    }
}

The next step will be to set a unique user identifier. Please note that without a unique identifier, the survey wall won't be available.

TapResearchSDK.SetUniqueUserIdentifier("<UNIQUE_USER_IDENTIFIER>");

Our system only accepts User IDs with ASCII characters. If necessary, you can convert it to BASE64 before sending the User ID to us.

Placements#

A Placement is an object that should be attached to the app's call to action that will direct the users to TapResearch.

To view the available placements or creating a new one, navigate to the app settings in the Supplier Dashboard, and copy the placement's identifier.

The Placement is encapsulated in the TRPlacement object which contains metadata and the method to display the survey wall.

Initialize a placement#

To initialize a placement, it is best practice to call the SDK as late as possible before displaying the placement in the app. For example, you can initialize it in the Start method of the scene where the placement will be visible.

public TRPlacement tapresearchPlacement;

void Start()
{
    TapResearchSDK.OnPlacementReady = this.OnPlacementReady;
    TapResearchSDK.InitPlacement(PlacementIdentifier)
}

void OnPlacementReady(TRPlacement placement)
{
    if (tapresearchPlacement.PlacementCode != TRPlacement.PLACEMENT_CODE_SDK_NOT_READY)
    {
        if (tapresearchPlacement.IsSurveyWallAvailable)
        {
            // Display the placement
        }
    }
    else
    {
        // Placement initialized before the SDK was ready
    }
}

More About Placements#

If initPlacement was called before the SDK initialization was completed, the SDK will return two placements: the first will return a placementCode with a value of PLACEMENT_CODE_SDK_NOT_READY and won't display the survey wall. The second placement response will occur once the SDK is initialized. The placement request will be fired and the callback will be triggered with a live placement.
The survey wall may or may not be available to a specific user and it's important to check survey availability before displaying the call to action.
A placement can only show the survey wall one time. Once the survey wall is dismissed, you'll have to initialize a new TRPlacement object if you wish the user to go back to TapResearch.

Display the survey wall#

To display the survey wall, call the ShowSurveyWall on your TRPlacement object.

myPlacement.ShowSurveyWall();

Going Live#

Learn how to take the app live.

Hot Survey#

hasHotSurvey is a placement attribute that indicates a special high-yield survey is available for this user. When this attribute is true, the user should be shown a special call to action to encourage them to take advantage of this opportunity. These special survey opportunities may only be available for a few minutes, so initPlacement should be called whenever the parent view is loaded. If you want to use Hot Surveys, please contact developers@tapresearch.com.

Rewards#

Server to server callbacks#

You can read more about server to server callbacks.

In-app Callbacks#

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

On SDK initialization
When the user exits TapResearch

The RewardListener interface is the reward listener that will handle the new rewards that the player earned in a session. The object that implements the interface should be passed to TapResearchSDK.getInstance().setRewardListener to get activated.

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 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.

public class MyMainController : MonoBehaviour {
    public void Awake() {
        TapResearchSDK.Configure (YOUR_API_TOKEN);
        TapResearchSDK.OnReceiveReward = this.OnReceiveReward;
    }

    private void OnReceiveReward(TRReward reward) {
      Debug.Log ("You've earned " + reward.RewardAmount + " " + reward.CurrencyName + ". " + reward.TransactionIdentifier);
    }
}

It is important to note that onReceiveReward will be called back-to-back if the player completed multiple surveys in one session.

Survey callback (Optional)#

Assign a delegate if you want to be notified when the survey wall status changes.

public class MyMainController : MonoBehaviour {
    public void Start() {
      TapResearchSDK.OnSurveyWallOpened = this.OnSurveyWallOpened;
      TapResearchSDK.OnSurveyWallDismissed = this.OnSurveyWallDismissed;
    }

    private void OnSurveyWallOpened () {
      // Stop music, timers, etc.
    }

    private void OnSurveyWallDismissed () {
      // Start music, timer, etc.
    }
}

Customize the survey wall#

If you wish to customize the look of the survey wall modal to fit with the rest of your game, use the following:

TapResearchSDK.SetNavigationBarText ("Title");
TapResearchSDK.SetNavigationBarTextColor ("#00ffff");
TapResearchSDK.SetNavigationBarColor ("#ff7f50");

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.

Android Debug Console Output#

To output debug info to logcat when generating an Android build, use the following:

#if UNITY_ANDROID
  TapResearchSDK.SetDebugMode (true);
#endif

Upgrade to v2.1#

In every file that will reference the SDK, add using TapResearch. All the SDK classes are under the TapResearch namespace.
The SDK API class was changed from TapResearch to TapResearchSDK. e.g. TapResearch.Configure is now TapResearchSDK.Configure
Delete the following files from the previous SDK
- TapResearch.cs
- Assets/Plugins/Android/tapresearch.aar
- Assets/Plugins/Android/unitybridge.aar
- Assets/Plugins/Android/play-services-ads-lite-10.2.6
- Assets/Plugins/Android/play-services-basement-10.2.6
- Assets/Plugins/iOS/TapResearchSDK.framework
Check the library dependency manager section for more info about library dependencies.

v2.0.0 Upgrade Notes#

The following methods and callbacks were removed from the SDK:

TapResearch.IsSurveyAvailable()
TapResearch.IsSurveyAvailable(identifier)
TapResearch.ShowSurvey()
TapResearch.ShowSurvey(String identifier)

TapResearch.OnSurveyModalOpened
TapResearch.OnSurveyModalDismissed
TapResearch.OnSurveyAvailable
TapResearch.OnSurveyAvailable

Upgrade from version v1.1.2#

In Assets > Plugins > Android, please delete the following:

apresearch.jar
unitybridge.jar
google-play-services_lib
Remove <activity android:name="com.tapr.internal.c.TRSurveyActivity"... from AndroidManifest.xml

Test Devices#

Before you are ready to go live, the SDK can only work with a test device. Navigate to your dashboard and click the Add Devices button. Add a device name and a unique user identifier or a Google Advertising ID / Apple IDFA. Now, when you enter our survey flow through your app, you will be able to complete a test survey and receive a test reward when you re-open your app.

Troubleshooting#

Survey wall isn't available#

If placement.IsSurveyWallAvailable is false, please reference the Android or iOS integration guides for further steps.

Contact#

Please send all questions, concerns, or bug reports to developers@tapresearch.com