espire-embed v1.1.0

Overview

The Espire embed project is available in two different ways:

• a ReactJS component
• a traditional Javascript library

If your website uses ReactJS, you must use the component (installable via npm) otherwise you will encounter display issues.

ReactJS

Installation

npm install --save espire-embed

Configuration

Before using the React component, you must instantiate the Espire class as it is required by the OfferWall. This is handled separate from the component so that it is possible to process conversions that occur while the component is not mounted. One way you could go about doing this is creating a file Espire.jsx with the following contents: (NOTE: this file is written using ES6 and flow for static type checking)

//@flow
import {Espire} from 'espire-embed';

let espire;

function setupEspire(userId: string, apiKey: string, onConversion?: (Conversion) => boolean) {
    espire = new Espire(userId, apiKey, onConversion);
}

export {
    setupEspire,
    espire
}

You can then set up the Espire class when instantiating your application like so:

import {setupEspire} from "./path/to/Espire.jsx";

setupEspire('<UUID>', '<API_KEY>', function(conversion) {
    // TODO: Handle conversion here
});

By doing it this way, you have the ability to show the OfferWall from multiple different components but still handle conversions in a single place, regardless of if the wall is actually visible.

Usage

Now that the Espire class has been set up, you can use the OfferWall component anywhere like so:

import React, {Component} from 'react';
import {OfferWall} from 'espire-embed';
import {espire} from './path/to/Espire.jsx';

class App extends Component {
    render() {
        return (
            <OfferWall espire={espire} title="TITLE" prompt="PROMPT"
                       onError={(errorMsg, error) => {}} 
                       onClose={() => {}} />
        );
    }
}

export default App;

Please note: The offer wall automatically opens when the component is rendered. Realistically, you will not want to show the wall at all times so it is up to you to determine when the component should be included while rendering (using state, redux, etc).

Web

Configuration

Insert the following code right before your closing </body> tag and perform the following steps:

<script type="text/javascript" src="https://apps.espireads.com/lib/embed.js"></script>
<script type="text/javascript">
    var espire = new Espire('<UUID>', '<API_KEY>', function(conversion) {
        // TODO: Handle conversions here
    });
</script>

1. Replace <UUID> with a unique user ID that represents the current active user. This will be used to map the conversion back to the user it was shown to.
2. Replace <API_KEY> with the provided API key.
3. Replace // TODO: Handle conversions here with whatever code should be executed when a user successfully converts on an offer (eg. resume locked video).

Usage

Show offers

To show the offer wall, all you need to do is call the show method (3rd parameter with callbacks is optional):

espire.show('TITLE', 'PROMPT', {
    onError: (errorMsg, error) => {}, // Handle error
    onClose: () => {}                 // Offer wall has been closed 
});

onConversion callback

If provided, this function will be called whenever an unacknowledged conversion has been found. Conversions will be automatically acknowledged by this library if the callback returns anything other than false (ie. undefined, true, null, etc. will all result in the conversion being acknowledged). If a conversion is not acknowledged, it will continuously be returned whenever this library checks for new conversions.

If you need to change the onConversion callback at any point after class instantiation, it can be reset by assigning a new function to the property:

espire.onConversion = function(conversion) { /* Handle conversion */ };

Notes

• Upon class instantiation (on page load if the script code was added right before the closing </body> tag as instructed), the library will automatically check if there are any unacknowledged conversions on the server.
• If more than one conversion is found, the onConversion callback will be fired multiple times, once for each conversion.
• The library will automatically begin polling the Espire API checking for conversions once the offer wall is shown so manually checking is not necessary. Once a conversion is returned matching the offer that was clicked, polling will stop.