TheoremReach Unity Integration Guide

Get Your API Key

Sign-up for a new developer account and create a new Unity app here and copy your API Key.

Download the Plugin

Download the latest version of the TheoremReach Unity Plugin here.

Import the Unity Package

From Unity go to Assets menu → Import package → Custom package → choose the unzipped unity package.

Android

Ensure the theoremreach-3.1.2.aar and other files were successfully imported with the TheoremReach.cs file in your "Assets/Plugins" folder.

In your player settings ensure the minimum API is set to 15 (Jelly Bean) or higher.

Initialize TheoremReach

We recommend initializing TheoremReach as soon as possible so we can begin preparing surveys for the user. In the Initialize method you'll set your API key and the user's ID that will be passed back into your server side callback when the user has earned currency for completing a survey.


  #if UNITY_ANDROID

  // Your GameObject that triggers the Reward Center
  void Start () {
    //initialize TheoremReach when your app starts with your API key and user ID that will be passed back to you in the server to server award callback
    TheoremReach.Initialize("YOUR_API_KEY", "YOUR_UNIQUE_USER_ID");
  }

  // Your GameObject that triggers the Reward Center
  void Update () {
    //logic for displaying surveys, e.g. clicking the Take Survey button
    if (TheoremReach.IsSurveyAvailable()) {
      TheoremReach.ShowRewardCenter();
    }
  }

  #endif 

Google Play Services

We require a Google Advertising ID in order to serve offers and surveys so you must add Google Play Services to your project in order to use the TheoremReach SDK. We provide the files to pull this in for you.

iOS

Ensure the TheoremReachWrapper.mm and TheoremReachWrapper.h files and frameworks folder are in your "Assets/Plugins/iOS" folder and the TheoremReach.cs file is in your "Assets/Plugins" folder.

Initialize TheoremReach

We recommend initializing TheoremReach as soon as possible so we can begin preparing surveys for the user. In the Initialize method you'll set your API key and the user's ID that will be passed back into your server side callback when the user has earned currency for completing a survey.


  #if UNITY_IOS

  // Your GameObject that triggers the Reward Center
  void Start () {
    //initialize TheoremReach when your app starts with your API key and user ID that will be passed back to you in the server to server award callback
    TheoremReach.Initialize("YOUR_API_KEY", "YOUR_UNIQUE_USER_ID");
  }

  // Your GameObject that triggers the Reward Center
  void Update () {
    //logic for displaying surveys, e.g. clicking the Take Survey button
    if (TheoremReach.IsSurveyAvailable()) {
      TheoremReach.ShowRewardCenter();
    }
  }

  #endif 

Libraries

We include a post processing script to automatically include all libraries into your project and perform any additional configuration in the build settings. See the iOS guide if you would like to verify your Xcode project setup.

Reward Callback

To ensure safety and privacy, we notify you of all awards via a server side callback. This callback will be triggered for both Android and iOS apps.

In the developer dashboard for your App add the server callback that we should call to notify you when a user has completed an offer. Note the user ID pass into the initialize call will be returned to you in the server side callback. More information about setting up the callback can be found in the developer dashboard.

The quantity value will automatically be converted to your virtual currency based on the exchange rate you specified in your app. Currency is always rounded in favor of the app user to improve happiness and engagement.

Client Side Award Callback

For security purposes we always recommend that developers utilize a server side callback, however we also provide APIs for implementing a client side award notification if you lack the server structure or a server altogether or want more real-time award notification. It's important to only award the user once if you use both server and client callbacks (though your users may not be opposed!).

In order to receive notifications you must implement the OnReward method on the GameObject you'd like to receive notifications that a user earned content. Then you must register that gameObject with the SetListener method.

Additionally you can also implement OnRewardCenterOpened and OnRewardCenterClosed to listen to events and TheoremReachSurveyAvailable to listen to when a survey is available.


  #if UNITY_ANDROID || UNITY_IOS

  // Your GameObject should receive the award notification. 
  // We recommend implementing this soon after the game loads.
  void Start () {
    TheoremReach.Initialize("YOUR_API_KEY", "YOUR_UNIQUE_USER_ID");

    // set the object that should receive the OnReward callback
    TheoremReach.SetListener("gameObject.name");
  }

  // implement method that will be called from TheoremReach SDK when a user earns content
  void OnReward(string quantity)
  {
    // award the content to the user
    Debug.Log("OnReward: " + quantity);
  }

  // Called when the reward center is open. Pause music, etc.
  void OnRewardCenterOpened()
  {
    Debug.Log("OnRewardCenterOpened");
  }

  // Called when the reward center is closed. Restart music, etc.
  void OnRewardCenterClosed()
  {
    Debug.Log("OnRewardCenterClosed");
  }

  // Called when a survey is available
  void TheoremReachSurveyAvailable(string available)
  {
    Debug.Log("TheoremReach TheoremReachSurveyAvailable: " + available);
  }

  #endif 

Contact

Please send all questions, concerns, or bug reports to admin@theoremreach.com.

FAQ

What do you do to protect privacy?

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

What kind of analytics do you provide?

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 hundreds 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'd love to help ensure everything flows smoothly and help you achieve your monetisation goals!