Integration

Including client.js

Production:

<script src="https://static.truex.com/js/client.js"></script>

Testing:

<script src="https://static.truex.com/js/client.test.js"></script>

An NPM package is available upon request.

The script defines the global truex object. For legacy integrations, the same object is also available as socialvibe.

Requesting and Showing an Ad

Define the options, initialize truex.client, and request an ad. If an ad is available, assign the event handlers and display the trigger point. When the user selects the trigger point, call client.loadAdIntoContainer (preferred) or client.openAdWindow (popup).

const options = {
  user_id: 'XXX',
  placement_hash: 'YYY',
};

truex.client(options, (client) => {
  client.requestAd((ad) => {
    if (!ad) {
      // No ad is available for this user
      return;
    }

    ad.onStart(() => console.log('start'));
    ad.onCredit((engagement) => console.log('credit', engagement.key));
    ad.onFinish(() => console.log('finish'));
    ad.onClose(() => console.log('close'));

    // Signal that the trigger point is shown
    client.trackTriggerPointImpression(ad);
    displayTriggerPoint(ad); // your call-to-action
  });
});

When the user selects the trigger point:

client.loadAdIntoContainer(ad, document.getElementById('ad-container'), {
  width: '100%',
  height: '100%',
});

Request a new ad in the onClose handler, so an expired ad is never shown. See the Examples page for a complete page.

Options

Parameter	Required	Type	Description
user_id	Yes	string	A partner-provided alphanumeric string that uniquely identifies the current user. The Advertising ID is recommended, if supported
placement_hash	Yes	string	The placement-specific identifier provided by Infillion
age		int	The user's age. Used for demographic targeting
gender		string	The user's gender: m for male, f for female, or x for non-binary. Used for demographic targeting
dimension_1 ... dimension_5		string	Slots for targetable metadata, for example a TV show name
handle_clickthrough_manually		boolean	For pages that run in a native app WebView. The clickthrough URL is passed to the onClickthrough handler instead of being opened by the ad

Client Methods

Method	Description
requestAd(callback)	Requests an ad. The callback receives the ad, or nothing if no ad is available
loadAdIntoContainer(ad, container, options)	Loads the ad iframe into container, a DOM element or the id of one. The optional options can set width, height, minWidth, and minHeight, as pixels (a number or '960px') or percentages ('100%'). width and height default to the size of the ad
openAdWindow(ad)	Opens the ad in a popup window. Use either this or loadAdIntoContainer
trackTriggerPointImpression(ad)	Optional Call it when the trigger point is displayed. Infillion uses it to calculate the click-through rate of your placement
trackOptOut(ad)	Optional Call it when the user decides not to engage, for example with a "no thanks" option on your trigger point. Used only for tracking
prepareAd(ad)	Attaches the event handlers to an ad object that you received from the Web Service API instead of requestAd

Deprecated Names

The following names are deprecated since June 2020. They keep working, so existing integrations do not need to change.

Deprecated	Replaced by
network_user_id	user_id
partner_config_hash	placement_hash
loadActivityIntoContainer	loadAdIntoContainer
openActivityWindow	openAdWindow
prepareActivity	prepareAd
trackImpression	trackTriggerPointImpression

Hybrid Mode

In hybrid mode, your server or native app requests the ad through the Web Service API, and a page in a WebView or a browser shows it. Use it when the ad request can't come from the page, for example when a native app handles the request and the targeting data.

Web Service API

GET https://get.truex.com/v2

For testing, use https://qa-get.truex.com/v2.

Parameter	Required	Type	Description
user.id	Yes	string	The same as user_id
placement.key	Yes	string	The same as placement_hash
ip	Server calls	string	The IP address of the user, used for geo-targeting
user_agent	Server calls	string	The URI-encoded user agent of the device
referrer		string	The URI-encoded URL of the page where the trigger point is shown
age, yob		int	The age or the 4-digit year of birth of the user
gender		string	m, f, or x
dimension_1 ... dimension_5		string	Slots for targetable metadata
coppa		boolean	1 if the user is under 13, 0 otherwise. Prevents the data from being stored
mraid		boolean	1 adds mraid.js to the ad markup

Sample request:

https://get.truex.com/v2?placement.key=YYY&user.id=XXX

The response is an ad JSON object, or {"error": "No bid found"} if no ad is available:

Field	Description
id	The id of the ad creative
campaign_id	The id of the ad campaign
name	The name of the ad creative
window_url	The URL that renders the ad
window_width, window_height	The size of the ad, in pixels. Size the container to this
currency_amount	The amount of your currency that the user earns for completing the ad
revenue_amount	The revenue you earn for the ad
session_id	The id of the current session

{
  "id": 7633,
  "campaign_id": 3802,
  "name": "Kung Fu Panda",
  "window_url": "https://qa-media.truex.com/...",
  "window_width": 960,
  "window_height": 500,
  "currency_amount": 2,
  "revenue_amount": "0.1",
  "session_id": "i_wktnzfS1G6yqdp57lSIw"
}

Showing the Ad in a WebView

Pass the response to a page that includes client.js. prepareAd attaches the event handlers and the tracking, so you receive the same events as with requestAd:

function showAd(placementHash, userId, ad) {
  const options = {
    user_id: userId,
    placement_hash: placementHash,
    handle_clickthrough_manually: true,
  };

  truex.client(options, (client) => {
    client.prepareAd(ad);

    // Pass the events to the native app, for example through a WebView message handler
    ad.onStart(() => sendToNative('onStart'));
    ad.onCredit((engagement) => sendToNative('onCredit', engagement));
    ad.onClickthrough((url) => sendToNative('onClickthrough', url));
    ad.onFinish(() => sendToNative('onFinish'));
    ad.onClose(() => sendToNative('onClose'));

    client.loadAdIntoContainer(ad, document.getElementById('ad-container'), {
      width: '100%',
      height: '100%',
    });
  });
}

sendToNative is yours: for example webkit.messageHandlers.<name>.postMessage on iOS or a @JavascriptInterface object on Android. The native app calls showAd after it loads the page.

NOTE

The client-side events come from client.js. If you load window_url in a WebView without client.js, the only completion signal is the server-side callback.