API integration

API Integration

The following defined Actors have been used

Server - Expressly API Server.

Publisher - The publisher Expressly is being configured with.

Customer - The customer interacting with the publisher using their browser.




Token check

Simple response message to check that the API key / token has been configured correctly including information about the installation. The endpoint as with all the authenticated endpoints should return a 401 if the token part of the Authorization header does not match the stored token.

Show Details




Retrieve user

Return a users data, via your application facilities, conforming to our defined entities. Additionally if the there is an event associated with the customer in the event they have purchased and airline or theatre ticket you MAY choose to pass the details using the eventData structure so that a receiving advertiser may use it to improve the migrated customer's experience such as when booking a taxi.

Show Details




Customers on Publisher

Given a list of emails, checks to see if a user already exists on the PUBLISHER.

Show Details

Serving

Serving

This section outlines how to retrieve a banner or creative for an active campaign, either directly from Expressly or from one of the supported ad servers


Directly From Expressly

To display banners of active campaigns to your registered customers, you will need to call the Expressly server banner endpoint with the customer's email address from your back-end to retrieve the image url and link url so that you can render the campaign banner on your page.

A banner is only returned on the following conditions:

  1. There is at least one active running campaign
  2. The customer does not already exist in the advertiser's customer database
  3. There is a banner that meets any size selection criteria

Please note that because the endpoint is secured with your API token and also contains the customer's e-mail address for security reasons you MAY only call the endpoint to retrieve the banner from your back-end server and it should not be called directly from the user's browser.




Get Banner

Fetch an eligible banner details for a given e-mail address. The width and height constrains of the banner are optional. For example

  •        width=728 - select a banner exactly 728px wide but any height
  •        height=90 - select a banner exactly 90px high but any width
  •        width=728&height=90 - select a banner exactly 728px wide and 90px high

Show Details


DoubleClick For Publishers (DFP)

Expressly also supports adding banners as creatives to DFP so that your running campaigns can be presented through Google tag ad units.

The Expressly line item and creatives should be configured to be displayed only if a user on your site is logged in. You can do this either by selectively showing the ad unit programmatically depending on the state of the user; or by using free-form key-value targeting that identifies the user's state.

Once configured the Expressly creative, if selected, will select the most appropriate Expressly campaign to display to the user from your campaigns.

To configure Expressly in DFP, you will need to do the following:

  1. Add an meta tag to your pages with the user's hashed e-mail address
  2. Add a custom creative to DFP with the Expressly code



META TAG AND EMAIL HASHING

In order for the Expressly creative to work you will need to hash the user's email address and add the hash to a meta tag on your page.

To hash the customer e-mail address, you will need to call an endpoint on the Expressly server. The hash returned will not change for a given e-mail address, so you may cache it for future use if you so wish.

Once you have the user's hashed email address, you can place in a meta tag in the head of the page on which the ad unit is placed.

    <meta property="xly:ppid" content="{hash}" />
                

Show Details




Adding the Creative to DFP

You will then need to configure the Line Item and targeting in DFP. To add the creative, you will need to select a creative type of Custom. In the Code Snippet text area, add the following:

<a href="%%CLICK_URL_UNESC%%" target="_blank" class="xly-creative">
                    <img width="%%WIDTH%%" height="%%HEIGHT%%" border="0">
                    </a>
                    <script type="text/javascript">
                    document.write('<scr' + 'ipt type="text/javascript" src="https://assets01.buyexpressly.com/adserving/adserver.js"><\/scr' + 'ipt>');
                    </script>
                

You MUST also uncheck the Serve into a SafeFrame check box. This allows access to the meta tag added to the page.




Other Ad Serving Platforms

We are adding support to more ad serving platforms. Please get in touch with us to check about yours. Contact us here.