Custom placement query

Use a custom placement to integrate Advisible ads in environments other than web, for example newsletters and mobile apps.

Endpoint

Authorization

An authorization token is required, which should be provided via the Authorization HTTP header. Create a new app token in Advisible Console and substitute [TOKEN] below.

Request

The endpoint accepts a request body of this type:

type CustomPlacementRequest = {
    publisherId: string
    placementName: string
    preview?: {
        adapterId: string
        code: string
    }
}

While developing the integration it can be helpful to use a preview request to get a test ad. The request below will return a generated ad using the settings on the given placement.

{
    "publisherId": "12345678",
    "placementName": "newsletter",
    "preview": {
        "adapterId": "com.advisible.content-display",
        "code": "generate-lorem"
    }
}

Just omit the preview field to make a live ad request instead.

{
    "publisherId": "12345678",
    "placementName": "newsletter"
}

Response

type CustomPlacementResponse = Array<{
    // The id of the adapter that produced the item.
    adapter: string

    // The item kind.
    kind: string

    // The ad item. This should be rendered by the integration.
    item: {
        id: string
        advertiser: string
        headline: string
        lead: string
        assetUrl: string
        url: string
    }

    // This value should not be used by the integration.
    key?: string
}>

The response consists of an array of ad items. The integration should be able to handle between zero and the configured maximum number of items, which is configured in the placement settings.

For example, if a custom placement is used to display native ads in a newsletter which has two ad slots, then the placement should be configured to deliver at most two ads. Depending on the current fill rate of the placement — zero, one, or two ads will be delivered. The system guarantees that the ads are unique to prevent duplicated content.

[{
    "adapter": "com.advisible.native.teaser",
    "item": {
        "id": "3bf04edb-b8b7-4cba-8e1c-5f9f7d7a3fa4",
        "advertiser": "Advertiser Name",
        "headline": "The headline",
        "lead": "The lead",
        "assetUrl": "https://media.advisible.com/...",
        "url": "https://www.example.com/..."
    },
    "key": "fe986e0c-6963-4ee7-8e02-dbe6feae7706"
}]

Most integrations only need to use the item field. Use the values to render the ad in an app, a newsletter or other custom environments. Here is an example of a simple native ad rendered with a common template syntax.

<a href="{{url}}">
    <label>ADVERTISEMENT</label>
    <img src="{{assetUrl}}">
    <h2>{{headline}}</h2>
    <div><span>{{advertiser}}</span>{{lead}}</div>
</a>