TapResearch JavaScript Integration Guide

Getting Started

Create an app and grab your API Token.

Embed the JavaScript loader

Add within your head tag. The TapResearch JS SDK will be asynchronously loaded without blocking your page load.

<script type="text/javascript">
!!function(e,t){window.TapResearch=t,t.loadLibrary=function(e){var o=document.createElement(&quot;script&quot;),a=document.getElementsByTagName(&quot;head&quot;)[0];o.src=t.host+&quot;/assets/sdk.js&quot;+(e?&quot;?ver=&quot;+e:&quot;&quot;),o.async=!0,a.appendChild(o),t.loadTimeout=setTimeout(function(){t.handleTimeout()},t.config.load_timeout||2e3)},t.init=function(e){t.config=e,t.host=&quot;https://www.tapresearch.com&quot;,t.loadLibrary()}}(document,window.TapResearch||[]);
</script>

Configure the SDK

<script type="text/javascript">
  TapResearch.init({
    api_token: "YOUR_API_TOKEN",
    user_identifier: "USER_ID",
    has_survey_callback: function(data) {
      // Add offer link (data.offer_url) to your page
    },
    no_survey_callback: function() {
      // Optional: suppress any loading message
    }
  });
</script>

user_identifier

user_identifier should be a persistent unique identifier (preferably hashed) for this user. This allows us to more accurately track users between sessions, to avoid asking the same profiling questions repeatedly. user_identifier will be used in scenarios where multiple users are seen on the same device.

has_survey_callback

This function is called when the JS SDK loads and has determined there is a survey available for this user. The function has one argument - an object like:

{
  has_offer: true
  message_hash: {min: "50", max: "200", currency: "coins"}
  offer_url: "https://tapresearch.com/router/offers/99678b60f874295ac4ac44c82bbd9dc3c0863f70/pre_entry?uid=38c346cbe20774e7b433e23815bff76c"
  sdk_version: 1
}

Where message_hash provides minimum and maximum reward amounts available given current survey inventory, and offer_url is the entry URL to the TapResearch router.

no_survey_callback

This function is called in two scenarios:

  1. The JS SDK loads and has determined there is no survey available for this user.
  2. The JS SDK is unable to load in a reasonable amount of time. The default is 2000ms. You can pass a different value (in ms) to the init() function as load_timeout.

Build the survey entry link

The API payload includes an offer_url property like:

https://tapresearch.com/router/offers/99678b60f874295ac4ac44c82bbd9dc3c0863f70/pre_entry?uid=38c346cbe20774e7b433e23815bff76c

Optional: Append a tid parameter with a unique transaction ID for this session. For example:

https://tapresearch.com/router/offers/99678b60f874295ac4ac44c82bbd9dc3c0863f70/pre_entry?uid=38c346cbe20774e7b433e23815bff76c&tid=asdf1234

This is useful to track performance if you have multiple entry points with your app. We will send this transaction ID back in the reward postback.

Server-to-server reward postback

Within your dashboard, configure a postback URL for your app.

Upon survey completion, we will call this post back with the user's transaction ID, user ID and payout amount. For more information, please visit our API docs.

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

Example app

Check out our example web app at: https://github.com/TapResearch/js-sdk-example

Contact

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

© 2024 TapResearch Inc.