TapResearch Unity Integration Guide

Getting Started

Important!!!

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.

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 so TapResearch can start getting surveys ready for your users. The Configure() method only needs to be called once on app launch. Also, your iOS and Android apps have different API tokens – use preproccessor directives so Unity knows which API token to use when you build your app.


  #if UNITY_IOS
    static String apiToken = "ios_api_token";
  #elif UNITY_ANDROID
    static String apiToken = "android_api_token";
  #endif

  public class MyMainController : Application {
      public void Awake() {
          TapResearch.Configure (apiToken);
      }
  }

Placements

A placement is the allocated section in your application where you want to provide access to TapResearch's survey wall, like an action button or a list item. To create a placement, navigate to the app settings in the supplier dashboard click settings and add the placement. The placement is encapsulated by the TRPlacement object which contains the placement 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 ()
  {
    TapResearch.OnPlacementReady = this.OnPlacementReady;
    TapResearch.InitPlacement(PLACEMENT_IDENTIFIER)
  }


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

Notice that the survey wall may or may not be available to a specific user and it's important to check survey availability before displaying the placement.

Please note that if the placement request was fired before that SDK is ready the OnPlacementReady will be called twice. The first time PlacementCode will return TRPlacement.PLACEMENT_CODE_SDK_NOT_READY indicating that the request was fired before the SDK was ready, the second call will return the latest placement from the server.

Display the survey wall

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


  myPlacement.ShowSurveyWall();

Please Note: 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 to keep the placement visible in the app.

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.

Reward notifications

Depending on your preferences the rewards notification will be posted to a url or will trigger an in-game game callback. Please follow the instructions below for server postback or in-game callback implementation

Server to server postback

If you set a postback URL for your app, you will be required to pass us a unique user identifier through the method shown below. This identifier will be included inside the postback payload. You should set the unique user identifier after you call the initWithApiToken() method. For more information, please visit our API docs.


  #if UNITY_IOS
    static String apiToken = "ios_api_token";
  #elif UNITY_ANDROID
    static String apiToken = "android_api_token";
  #endif

  public class MyMainController : Application {
      public void Awake() {
          TapResearch.Configure (API_TOKEN);
          TapResearch.SetUniqueUserIdentifier ("<UNIQUE_USER_IDENTIFIER>");
      }
  }

In-Game callback

Add a reward listener so we can notify you when a user completes a survey. The quantity value will automatically be converted to your virtual currency based on the exchange rate you specified in your app settings. It is important to note that this method may be called back to back if the player completed multiple surveys in one session.


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

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

Survey callback (Optional)

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


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

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

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

Customise the survey wall

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


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

Android Debug Console Output

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


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

Upgrade to v2.0.0

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, it is important that your reward callback is working properly. Navigate to your dashboard and click the Add Devices button. Add a device name and your Google Advertising ID. 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

FAQ

Do we have to pay to use the TapResearchSDK?

No. Our SDK is completely free of charge. In fact, we pay you every time a user completes a survey.

What measures do you take to protect user privacy?

We take user privacy very seriously. All data is encrypted before being sent over the network. Furthermore, we use HTTPS to ensure the integrity and privacy of the exchanged data.

What kind of analytics do I have access to?

Our dashboard will show metrics for sessions, impressions, revenue, and much more. We are constantly enhancing our analytics so we can better serve your needs.

What is your fill rate?

We have thousands of surveys and add a few hundred more every day. Most users will have the opportunity to complete at least one survey on a daily basis.

I'm ready to go live! What are the next steps?

Let us know! We need to update the status of your app so your users can see real surveys. Note, test devices will only be able to see a test survey.