Integration Guides

In this section you can find a few examples of typical integrations with various platforms or for a certain, specific use case. In most cases we will aim to have a turnkey solution with as many partners as possible but if not, you might find some inspiration or best practices here that might come in handy when venturing into uncharted terrain.

Using data push for Ad Servers or other services

You can use our data push feature to provide your app with a pre-filled request URL to an ad server, such as our own miyuki system, or indeed, any other service responding to personalised GET requests.

Based on how many placements you have configured for your app you will have to make equally as many matching data campaigns as each will make a request for one specific placement.

The first thing to do is to decide on a convention on how you deliver the links. You should provide a meaningful name such as ad_request_url so that your app will be able to respond and route the content to the correct display container in your app.

You should create data campaigns which include this key name and a value of the ad server request URL, adding any device or personalisation attributes as required; for example, if the ad server asks for the operating system or operating system version on some parameter, you can use the device.os or device.osv macros to have this automatically filled for a user at the time of sending the message.

Here is an example below for a minimal request for offerwall content to the 360dialog miyuki ad server, this should be the payload of your data push:

{
  "miyuki_request_url": "https://service.miyuki.mobi/service/offerwall-template.php?mm_ch={{trigger.channel}}&mm_pl={{trigger.placement}}&mm_c={{device.country}}&mm_l={{device.language}}&mm_userid={{custom.external_user_id}}&mm_dvidfa={{device.ifa}}&mm_os={{device.os}}"
}

Check the documentation for the ad server you are using to make sure you can deliver all necessary values, there might be more, such as geo coordinates that you can enrich your request with based on more up to date information taken directly from the device itself. Generally you will need at least the country, language, operating system, advertising id and some user id as well as the name or id of the channel and placement you are requesting an ad for.

You should trigger your campaign on a specific event being fired from your app, we’ll get to the campaign configuration later on in the doc but before that we’ll need to configure the app. We should fire this event each time a user lands on a page with an ad banner plcehlder or where a full screen interstitial ad should be displayed. As we can also trigger based on specific properties of an event we could use a generic miyuki_ad_request event in the app and give it a placement property which would take the name of the placement you are requesting an ad for as well as a channel property which will be the name of your channel. This is important as these values will be used to personalise the ad request, so remember to make sure the property names in your campaign match the ones in your event and that the values match the channel and placement ids or other identifier that your ad serving system uses to identify you as a customer and this ad space as a defined placement.

For example, for an iOS app in swift you would use something like:

let parameters: [String: AnyObject] = [
    "placement": "MY_PLACEMENT_NAME" as AnyObject,
    "channel": "MY_CHANNEL_NAME" as AnyObject
]

D360.events().logCustomEvent(name: "miyuki_ad_request", parameters: parameters)
D360.events().flush()

Note how we flush the event instantly, meaning this and any other queued requests get sent to the backend straight away, bypassing any cache or other delays.

We’ll set up our data campaign to trigger on the event miyuki_ad_request with the property placement having the value MY_PLACEMENT_NAME.

For a banner ad, the banner space you’d like to fill should take the value of the miyuki_request_url field you will receive in the data push as its content. The banner space you use must support javascript and should be configured to open links in the external browser rather than inside its own bounds.

If you are using full screen interstitials you can either use the data push method described above and provide a full screen window into which to deliver the content or simply configure an inapp overlay campaign with your ad server request url as the source of your custom HTML content. You should use the same procedure in the app to create an event with a unique name for the ad request and a property name whose value is the name of your placement; as stated above, these will be used to make the request.

If using overlays you will have to make sure that the HTML template is compatible with the 360dialog SDK. This involves simply making sure that your clickable links are delivered according to our action JSON specification so that user interaction such as clicks or closing the overlay can be properly tracked in the 360dialog Xray CRM.

Links should follow this convention (showing the unencoded format first):

d360://action?actionJSON={"n":"openURL","p":{"u":"https://YOURCTA.com/link"}}

Where everything that follows after the ‘=’ is URL encoded and so will finally look like this in the rendered HTML.

d360://action?actionJSON=%7B%22n%22%3A%22openURL%22%2C%22p%22%3A%7B%22u%22%3A%22https%3A%2F%2FYOURCTA.com%2Flink%22%7D%7D

When you’re all done you will something that acts a little like this: