New blog post!

How You Can 2X Your App or Website Revenue

Choose your integration guide

Get Your API Key

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

Install SDK

Install via Cocoapods (easiest)


// add to your Podfile:
pod 'TheoremReach', '3.3.6'

// pod repo update
// pod install

Or Manually Download the SDK

Download the latest version of the iOS SDK here.

Libraries

  • Add the TheoremReachSDK.framework file to the link binary with libraries section under the Build Phases tab (or Embedded Binaries on the General tab if you’re using xcode 7):
    • TheoremReachSDK.framework
  • Add the following required frameworks:
    • AdSupport.framework
    • CoreTelephony.framework
    • Foundation.framework
    • JavaScriptCore.framework
    • Security.framework
    • SystemConfiguration.framework
    • UIKit.framework
  • And the following optional frameworks:
    • Webkit.framework

Flags

  • On the Build Settings tab and type in Other Linker Flags in the search field.
  • Add the following flags.
    • -ObjC

Set Required Build Settings

  • We utilize Apple’s Advertising ID (IDFA) to identify users. When uploading your app we recommend that you check all the boxes to note that your app uses IDFA and receives a smooth approval process.
  • On the Info tab add in a Dictionary called NSAppTransportSecurity. Make sure you add this dictionary on the Top Level Key. Inside this dictionary, add a Boolean called NSAllowsArbitraryLoads and set it to YES. An example of your info.plist can be found here.

Initialize

After you have finished modifying the project settings, open your AppDelegate.h file and import the TheoremReach SDK. Replace the YOUR_API_TOKEN with the actual api key found on your app. Replace YOUR_USER_ID with your unique ID for your appuser. If you do not have a unique user ID we recommend just using their Apple Advertising ID (IDFA). If you utilize a server-side callback, this is the user ID that will be passed back to you when a user earns a reward.


// AppDelegate.h
#import <TheoremReachSDK/TheoremReach.h>

Next initialize the TheoremReach SDK in your applicationDidFinishLaunchingWithOptions method.


// AppDelegate.m

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
// Your code logic

[TheoremReach initWithApiKey:@"YOUR_API_TOKEN" userId:@"YOUR_USER_ID"];

}

Reward Center

Open the .m file of the controller where you want your users to have access to TheoremReach Reward Center. Call the displayRewardCenter method when you are ready to the send the user into the reward center where they can complete surveys in exchange for your virtual currency. We automatically convert the amount of currency a user gets based on the conversion rate specified in your app.


#import <TheoremReachSDK/TheoremReach.h>

- (IBAction)rewardCenterButtonClicked:(id)sender
{
// if a survey is available, show the reward center
if ([TheoremReach getInstance].isSurveyAvailable) {
[TheoremReach showRewardCenter];
}
}

Reward Callback

To ensure safety and privacy, we notify you of all awards via a server side callback. 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!).


#import <TheoremReachSDK/TheoremReach.h>

@interface YourClass : YourClassSuperclass <TheoremReachRewardDelegate>

// Set the TheoremReach delegate to the class that you'd like to receive award callbacks
[[TheoremReach getInstance] setRewardDelegate:self];

// implement the 'onReward: (NSNumber* )quantity' method in your delegate
- (void)onReward: (NSNumber* )quantity {
// award user the content!
NSLog(@"onReward: %@", quantity);
}

Reward Center Events

You can optionally listen for the onRewardCenterOpened and onRewardCenterClosed events by implementing the TheoremReachSurveyDelegate methods.


#import <TheoremReachSDK/TheoremReach.h>

@interface YourClass : YourClassSuperclass <TheoremReachSurveyDelegate>

// Set the TheoremReach delegate to the class that you'd like to receive award callbacks
[[TheoremReach getInstance] setSurveyListenerDelegate:self];

// implement the 'onRewardCenterClosed' and 'onRewardCenterOpened' methods in your delegate

- (void)onRewardCenterOpened {
// reward center opened! Time to take surveys!
NSLog(@"onRewardCenterOpened");
}

- (void)onRewardCenterClosed {
// reward center opened! Back to the app to use our coins!
NSLog(@"onRewardCenterClosed");
}

Survey Available Callback

If you’d like to be notified when a survey is available you can add a listener:


#import <TheoremReachSDK/TheoremReach.h>

@interface YourClass : YourClassSuperclass <TheoremReachSurveyAvailableDelegate>

// Set the TheoremReach delegate to the class that you'd like to receive survey available callbacks
[[TheoremReach getInstance] setSurveyAvailableDelegate:self];

// implement the 'theoremreachSurveyAvailable: (BOOL)surveyAvailable' method in your delegate
- (void)theoremreachSurveyAvailable: (BOOL)surveyAvailable {
if (surveyAvailable) {
NSLog(@"TheoremReach survey available!");
} else {
NSLog(@"TheoremReach survey not available!");
}
}

Testing SDK

When you initially create your app we automatically set your app to Test mode. While in test mode a survey will always be available. Note – be sure to set your app to Live in your dashboardt before your app goes live or you won’t serve any real surveys to your users!

Customizing SDK

We provide several methods to customize the navigation bar to feel like your app.


[TheoremReach getInstance].navigationBarTextColor = @"#FFFFFF";
[TheoremReach getInstance].navigationBarText = @"iOS Demo App";
[TheoremReach getInstance].navigationBarColor = @"#17b4b3";

Contact

Please send all questions, concerns, or bug reports to publishers@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!

Get Your API Key

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

Install SDK

Gradle Install via jCenter()


compile 'com.google.android.gms:play-services-ads:15.0.1'
compile 'com.theoremreach:theoremreach:3.3.5'

Or Manually Download the SDK

Download the latest version of the Android SDK here. Add the theoremreach-3.3.5.aar file to your projects “libs” folder.

Update your module’s build.gradle file

Include the theoremreach.aar, Google Play Services and appcompat in your build.gradle file. We require a Google Advertising ID in order to serve offers and surveys so you must add the Google Play Services SDK to your project in order to use the TheoremReach SDK. Be sure your minSdkVersion is set to at least 15.


apply plugin: 'com.android.application'
...

android {
...
defaultConfig {
...
minSdkVersion 15
...
}
...
}

dependencies {
...
compile 'com.google.android.gms:play-services-ads:15.0.1'
compile (name: 'theoremreach-3.3.5', ext: 'aar')
}

Update your projects’s build.gradle file

Ensure that your project has access to the ‘libs’ file by including the following in your project level build.gradle file.


buildscript...

allprojects {
repositories {
jcenter()
flatDir {
dirs 'libs' } } }

Proguard

If you use proguard in your app. Be sure to add this line to your rules file:



-keep class theoremreach.com.** { *; }

Initialize TheoremReach

In your activity overwrite the onCreate() method and initialize the TheoremReach SDK with the initWithApiKeyAndUserIdAndActivityContext call. And implement the TheoremReach onPause() and onResume() calls. Replace the YOUR_API_TOKEN with the actual api key found on your app. Replace YOUR_USER_ID with your unique ID for your appuser. If you do not have a unique user ID we recommend just using their Google Advertising ID (GPS_ID)


public class MyActivity extends Activity {
@Override
public void onCreate() {
super.onCreate();
TheoremReach.initWithApiKeyAndUserIdAndActivityContext("YOUR_API_TOKEN", "YOUR_USER_ID", "YOUR_ACTIVITY");
}

@Override
protected void onResume() {
super.onResume();
TheoremReach.getInstance().onResume(this);
}

@Override
protected void onPause() {
super.onPause();
TheoremReach.getInstance().onPause();
}
}

Reward Center

Next, in your activity, implement the logic to display the reward center. Call the showRewardCenter method when you are ready to the send the user into the reward center where they can complete surveys in exchange for your virtual currency. We automatically convert the amount of currency a user gets based on the conversion rate specified in your app.


this.rewardCenterButton.setOnClickListener(new View.OnClickListener() {
@Override
public void onClick(View v) {
// if a survey is available, show the reward center
if (TheoremReach.getInstance().isSurveyAvailable()) {
TheoremReach.getInstance().showRewardCenter();
}
}
});

Reward Callback

To ensure safety and privacy, we notify you of all awards via a server side callback. 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!).


public class MyActivity extends Activity implements TheoremReachRewardListener {

@Override
protected void onCreate(Bundle savedInstanceState) {
...
// initialize TheoremReach
super.onCreate();
TheoremReach.initWithApiKeyAndUserIdAndActivityContext("YOUR_API_TOKEN", "YOUR_USER_ID", "YOUR_ACTIVITY");

// set TheoremReach client-side reward listener
TheoremReach.getInstance().setTheoremReachRewardListener(this);

}

// implement callback for award notification
@Override
public void onReward(int quantity) {
Log.d(TAG, "onReward: " + quantity);
}
}

Reward Center Events

You can optionally listen for the onRewardCenterOpened and onRewardCenterClosed events by implementing the TheoremReachSurveyListener interface.


public class MyActivity extends Activity implements TheoremReachSurveyListener {

@Override
protected void onCreate(Bundle savedInstanceState) {
...
// initialize TheoremReach
super.onCreate();
TheoremReach.initWithApiKeyAndUserIdAndActivityContext("YOUR_API_TOKEN", "YOUR_USER_ID", "YOUR_ACTIVITY");

// set TheoremReach survey event listener
TheoremReach.getInstance().TheoremReachSurveyListener(this);

}

// reward center opened. time to start earning content!
@Override
public void onRewardCenterOpened() {
Log.d(TAG, "onRewardCenterOpened");
}

// reward center closed. restart music/app.
@Override
public void onRewardCenterClosed() {
Log.d(TAG, "onRewardCenterClosed");
}
}

Survey Available Callback

If you’d like to be notified when a survey is available you can add a listener:


public class MyActivity extends Activity implements TheoremReachSurveyAvailableListener {

@Override
protected void onCreate(Bundle savedInstanceState) {
...
// initialize TheoremReach
super.onCreate();
TheoremReach.initWithApiKeyAndUserIdAndActivityContext("YOUR_API_TOKEN", "YOUR_USER_ID", "YOUR_ACTIVITY");

// set TheoremReach survey available listener
TheoremReach.getInstance().setTheoremReachSurveyAvailableListener(this);

}

// implement callback for survey available
@Override
public void theoremreachSurveyAvailable(int surveyAvailable) {
Log.d(TAG, "theoremreachSurveyAvailable: " + surveyAvailable);
}
}

Testing SDK

When you initially create your app we automatically set your app to Test mode. While in test mode a survey will always be available. Note – be sure to set your app to Live in your dashboardt before your app goes live or you won’t serve any real surveys to your users!

Customizing SDK

We provide several methods to customize the navigation bar to feel like your app.


TheoremReach.getInstance().setNavigationBarText("Demo App");
TheoremReach.getInstance().setNavigationBarColor("#17b4b3");
TheoremReach.getInstance().setNavigationBarTextColor("#FFFFFF");

Contact

Please send all questions, concerns, or bug reports to publishers@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!

Get Your API Key

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

There are three different ways to work with the TheoremReach web app. You can host our site as an iframe within your existing website, you can open our page in a new tab, or you can use our javascript SDK to displays a modal window with our site that automatically resizes based on the device size

Hosting our site as an iframe

Simply load the URL within your site as an iframe using the user’s ID and your apps API key:


iframe src="https://theoremreach.com/respondent_entry/direct?api_key={YOUR_API_KEY}&user_id={YOUR_UNIQUE_USER_ID}"

Open TheoremReach Directly

Simply open the URL in a new tab


href="https://theoremreach.com/respondent_entry/direct?api_key={YOUR_API_KEY}&user_id={YOUR_UNIQUE_USER_ID}" target="_blank"

Javascript SDK

Include the required javascript files:


<script type="text/javascript" src="https://code.jquery.com/jquery-3.2.1.min.js"></script>
<script type="text/javascript" src="https://s3.amazonaws.com/cdn.theoremreach/v3/theorem_reach.min.js"></script>

Initialize TheoremReach

We recommend initializing TheoremReach as soon as possible in your code so that we can begin getting surveys ready for the user.


// setup your config object and initialize TheoremReach

// optionally include callbacks when the reward center opens and closes
function onRewardCenterOpened(){
console.log("onRewardCenterOpened");
}

function onReward(data){
console.log("onReward: " + data.earnedThisSession);
}

function onRewardCenterClosed(){
console.log("onRewardCenterClosed");
}

<script>
var theoremReachConfig = {
apiKey: "YOUR_API_KEY",
userId: "YOUR_UNIQUE_SERVER_USER_ID",
idfa: "USERS_APPLE_ADVERTISING_ID", // optional. If iOS, set the Apple IDFA to ensure the most number of surveys are available
gpsId: "USERS_GOOGLE_ADVERTISING_ID", // optional. If Android, set the Google Advertising ID 
onRewardCenterOpened: onRewardCenterOpened,
onReward: onReward,
onRewardCenterClosed: onRewardCenterClosed
};

var TR = new TheoremReach(theoremReachConfig);

</script>

Reward Center

Next, implement the logic to display the reward center. Call the showRewardCenter() method when you are ready to the send the user into the reward center where they can complete surveys in exchange for your virtual currency. We automatically convert the amount of currency a user gets based on the conversion rate specified in your app.

You can optionally check to see if the user has a survey available to take before launching the reward center with the isSurveyAvailable() method. Note – this method will return true only after the SDK has completely finished initializing.


if (TR.isSurveyAvailable()) {
TR.showRewardCenter();
}

// implemented as an onclick method in a button:
<button class="button" onclick="if (TR.isSurveyAvailable()) {TR.showRewardCenter()}">Take Surveys, Earn Coins!</button>

Reward Callback

To ensure safety and privacy, we notify you of all awards via a server side callback. 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 that the user ID passed into the initialize call will be returned to you in the server side callback. More information about setting up and testing the callback can be found in your app 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.

Contact

Please send all questions, concerns, or bug reports to publishers@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!

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

// notify TheoremReach OnResume
void OnApplicationFocus (bool hasFocus) {
if (hasFocus) TheoremReach.OnResume();
}

// notify TheoremReach OnPause
void OnApplicationPause (bool pauseStatus) {
if (pauseStatus) TheoremReach.OnPause();
}

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

Placements

Often times publishers want to offer more than one currency to users within an app. This is easily achieve via Placements! Simply create a new placement in your app dashboard and configure the currency name and exchange rate. Then grab your placement ID. Note – these can also be used to offer higher or lower exchange rates to your users based on user segmentation (e.g. higher to non-payers and lower to whales).


#if UNITY_ANDROID || UNITY_IOS

// 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("YOUR_PLACEMENT_ID");
}
}

#endif 

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 

 

Testing SDK

When you initially create your app we automatically set your app to Test mode. While in test mode a survey will always be available. Note – be sure to set your app to Live in your dashboardt before your app goes live or you won’t serve any real surveys to your users!

Customizing SDK

We provide several methods to customize the navigation bar to feel like your app.


TheoremReach.SetNavigationBarText("Testing Demo");
TheoremReach.SetNavigationBarColor("#17b4b3");
TheoremReach.SetNavigationBarTextColor("#FFFFFF");

Contact

Please send all questions, concerns, or bug reports to publishers@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!