Creative Custom Request Template service
Note
This service is currently available to a limited set of clients and Microsoft employees only.
To support mobile ad server mediation, Xandr uses a mediated creative type. Unlike standard creatives, which reside as static content on a server, mediated creatives are configurable containers that fetch server side content. The Creative Custom Request Template Service is used to build the requests that populate these mediated creatives. It does this by managing a set of custom templates, each of which will correspond to a different ad server, and which is associated with a template "type" defined by the Creative Custom Request Template Type Service.
This document describes the fields made available by this API service, as well as providing usage examples. See the Examples section below.
Note
For more information about mediated creatives, see the Creative Service.
For a list of supported query string parameters and macros, see Creative Custom Request Template Parameters.
REST API
Note
This information is for Xandr employees. If you are an employee and an admin user, your permissions are as follows:
- You will see the global templates.
- You can view member-specific templates by appending
a =member_id=field
to the query string of your request.
Template Viewing Permissions:
If you are a member you will be able to view the following templates:
- Global templates (those belonging to
member_id
=0). - Your own templates, i.e., those associated with your
member_id
.
HTTP Method | Endpoint | Description |
---|---|---|
POST |
https://api.appnexus.com/creative-custom-request-template | Create a custom request template. |
GET |
https://api.appnexus.com/creative-custom-request-template?id=123 | View a specific custom request template. |
GET |
- https://api.appnexus.com/creative-custom-request-template?member_id=0 - https://api.appnexus.com/creative-custom-request-template?member_id=YOUR_MEMBER_ID |
View all of the custom request templates you have permission to view. |
PUT |
https://api.appnexus.com/creative-custom-request-template | Update a custom request template. |
DELETE |
https://api.appnexus.com/creative-custom-request-template?id=123 | Delete a custom request template. |
GET |
https://api.appnexus.com/creative-custom-request-template/meta | Find out which fields you can filter and sort by. |
JSON fields
Name | Type | Description |
---|---|---|
macros |
array of objects | These are the macros (or query string parameters) that will be sent on the request. See Macros. Sort by: No Filter by: No |
id |
int | The ID of this template. Required On: PUT Sort by: Yes Filter by: Yes |
type_id |
int | The ID of the Creative Custom Request Template Type associated with this template. Default: null Required On: POST Sort by: Yes Filter by: Yes |
member_id |
int | The member ID whose mediation creatives will be associated with this template. For more information see the Creative Service and the Member Service. Default: 0 Sort by: Yes Filter by: Yes |
media_subtype_id |
int | The media subtype ID for this template. Derived from the Media Subtype object below. Default: null Sort by: Yes Filter by: Yes |
hostname |
string | The hostname of the ad server we're building a mediation request for. Default: null Required On: POST Sort by: Yes Filter by: Yes |
uri |
string | The full URI of the external ad server to which we'll send our request. Default: null Required On: POST , PUT if is_client is false . Sort by: Yes Filter by: Yes |
port |
int | The port on the external ad server to which we'll send our request. Default: 80 Sort by: Yes Filter by: Yes |
is_post |
Boolean | Whether the HTTP request we're making is a POST .Default: false Sort by: Yes Filter by: Yes |
content |
string | The content payload we're sending with the request. For example, this may be a string of JSON or XML. Default: null Sort by: Yes Filter by: Yes |
timeout_ms |
int | The timeout supported by that ad server (Or the timeout we're going to impose on waiting for that ad server). Default: 0 Sort by: Yes Filter by: Yes |
is_client |
Boolean | Whether the request is originating from an HTTP client (for example, an SDK). Default: false Sort by: Yes Filter by: Yes |
media_subtype |
array | The display style of creatives that can use this template. Each media subtype belongs to a superordinate media type. For example, the "Standard Banner" media subtype belongs to the "Banner" media type. For more details, see Media Subtype below. Sort by: No Filter by: No |
last_modified |
date | The date and time at which this object was last updated. Sort by: Yes Filter by: Yes |
Macros
Name | Type | Description |
---|---|---|
id |
int | The ID of this macro. Default: null Sort by: Yes Filter by: Yes |
template_id |
int | The Creative Custom Request Template this macro is associated with. Default: null Sort by: Yes Filter by: Yes |
code |
string | The query string parameter that will be built into the url, e.g., send_referer .Sort by: Yes Filter by: Yes |
name |
string | A description of what the macro does, e.g., "Toggle if referer should be sent". Sort by: Yes Filter by: Yes |
type |
string | The type of value the parameter will accept. Note: The default value of "string" is also the most common. Allowed values include:- true_false - string - url - integer - decimal - string_list - select_from_list Default: string Sort by: Yes Filter by: Yes |
is_required |
Boolean | Whether this macro is required in a call to the external ad server. Default: true Sort by: Yes Filter by: Yes |
last_modified |
date | The date and time at which this macro object was last updated. Sort by: Yes Filter by: Yes |
Media subtype
You can use the Media Subtype Service and Media Type Service to view all supported media subtypes and the media types to which they belong. For a general definition of each supported media type, see Supported Media Types.
Field | Type | Description |
---|---|---|
id |
int | The ID of the media subtype. |
name |
string | Read Only. The name of the media subtype. |
media_type_name |
string | Read Only. The name of the media type to which the subtype belongs. |
mediatype_id |
int | Read Only. The ID of the media type to which the subtype belongs. |
Examples
View all creative request templates (that you have permissions to view)
In the example below, note the difference between how standard Xandr macros are displayed in the uri
field, e.g., * $\{USER_IP\}
and how the custom macros defined on a per-ad-server basis by this service are displayed: * \#\{MK_SITEID\}
. You can see definitions for each macro in the macros
array of objects below. You will only be able to view request templates belonging to your own member ID or public templates belonging to member ID 0
.
{code}
$ curl -b cookies https://api.appnexus.com/creative-custom-request-template?member_id=0
{
"response": {
"status": "OK",
"count": 4,
"start_element": 0,
"num_elements": 100,
"creative-custom-request-templates": [
{
"id": 1,
"type_id": 2,
"member_id": 0,
"media_subtype_id": 1,
"hostname": "w.inmobi.com",
"uri": "/showad.asm?mk-siteid=#{MK_SITEID}&mk-carrier=${USER_IP}&h-user-agent=${USER_AGENT_ENC}&h-referer=${REFERER_URL_ENC}&u-id-map=${INMOBI_UID_MAP}&u-latlong-accu=${INMOBI_LAT_LONG_ACCU}&u-age=${AGE}&u-gender=${GENDER}&d-localization=${USER_LOCALE}&d-nettype=${INMOBI_NETTYPE}&d-orientation=${INMOBI_ORIENTATION}",
"port": 80,
"is_post": false,
"content": "",
"timeout_ms": 200,
"is_client": false,
"last_modified": "2013-07-10 19:27:41",
"media_subtype": {
"id": 1,
"name": "Standard Banner",
"media_type_name": "Banner",
"mediatype_id": 1
},
"macros": [
{
"id": 1,
"template_id": 1,
"code": "MK_SITEID",
"name": "MK_SITEID",
"type": "string",
"is_required": true,
"last_modified": "2013-07-10 19:27:41"
}
]
},
{
"id": 2,
"type_id": 3,
"member_id": 0,
"media_subtype_id": 1,
"hostname": "ads.mydas.mobi",
"uri": "/getAd?apid=#{APID}&auid=${DEVICE_MD5}&ua=${USER_AGENT_ENC}&uip=${USER_IP}&age=${AGE}&gender=${GENDER}&zip=${POSTAL_CODE}&lat=${GEO_LAT}&long=${GEO_LON}",
"port": 80,
"is_post": false,
"content": "",
"timeout_ms": 200,
"is_client": false,
"last_modified": "2013-07-10 19:27:50",
"macros": [
{
"id": 2,
"template_id": 2,
"code": "APID",
"name": "APID",
"type": "string",
"is_required": true,
"last_modified": "2013-07-10 19:27:50"
}
]
},
{
"id": 3,
"type_id": 4,
"member_id": 0,
"media_subtype_id": 5,
"hostname": "ads.mojiva.com",
"uri": "/ad?zone=#{ZONE}&ip=${USER_IP}&ua=${USER_AGENT_ENC}&url=${REFERER_URL_ENC}&udid=${DEVICE_MD5}&lat=${GEO_LAT}&long=${GEO_LON}&country=${USER_COUNTRY}®ion=${USER_STATE}&city=${USER_CITY}&dma=${USER_DMA}&zip=${POSTAL_CODE}",
"port": 80,
"is_post": false,
"content": "",
"timeout_ms": 200,
"is_client": false,
"media_subtype": {
"id": 1,
"name": "Standard Banner",
"media_type_name": "Banner",
"media_type_id": 1
},
"last_modified": "2013-07-10 19:28:00",
"macros": [
{
"id": 3,
"template_id": 3,
"code": "ZONE",
"name": "ZONE",
"type": "string",
"is_required": true,
"last_modified": "2013-07-10 19:28:00"
}
]
},
{
"id": 4,
"type_id": 5,
"member_id": 0,
"media_subtype_id": 5,
"hostname": "a.jumptap.com",
"uri": "/a/ads?hid_sha1=${DEVICE_SHA1}&idfa=${DEVICE_APPLE_IDA}&pub=#{PUB}&site=#{SITE}&spot=#{SPOT}&url=${REFERER_URL_ENC}&ua=${USER_AGENT_ENC}&client-ip=${USER_IP}&country=${USER_COUNTRY}&ll=${JUMPTAP_LAT_LONG_ENC}&mt-age=${AGE}&mt-gender=${GENDER}",
"port": 80,
"is_post": false,
"content": "",
"timeout_ms": 200,
"is_client": false,
"media_subtype": {
"id": 5,
"name": "Interstitial",
"media_type_name": "Interstitial",
"media_type_id": 3
},
"last_modified": "2013-07-10 19:28:10",
"macros": [
{
"id": 4,
"template_id": 4,
"code": "PUB",
"name": "PUB",
"type": "string",
"is_required": true,
"last_modified": "2013-07-10 19:28:10"
},
{
"id": 5,
"template_id": 4,
"code": "SITE",
"name": "SITE",
"type": "string",
"is_required": true,
"last_modified": "2013-07-10 19:28:10"
},
{
"id": 6,
"template_id": 4,
"code": "SPOT",
"name": "SPOT",
"type": "string",
"is_required": true,
"last_modified": "2013-07-10 19:28:10"
}
]
}
],
"dbg_info": {
"instance": "28.bm-hbapi.prod.nym1",
"s1ave_hit": true,
"db": "141.bm-mysql.prod.nym1",
"reads": 1,
"read_limit": 100,
"read_limit_seconds": 60,
"writes": 0,
"write_limit": 60,
"write_limit_seconds": 60,
"awesomesauce_cache_used": false,
"count_cache_used": false,
"warnings": [],
"time": 66.461801528931,
"start_microtime": 1373651335.4519,
"version": "1.13.52",
"s1ave_lag": 1,
"member_last_modified_age": 68896
}
}
}
{code}
View a single creative custom request template
{code}
$ curl -b cookies https://api.appnexus.com/creative-custom-request-template?id=2
{
"response": {
"status": "OK",
"count": 1,
"start_element": 0,
"num_elements": 100,
"creative-custom-request-template": {
"id": 2,
"type_id": 3,
"member_id": 0,
"media_subtype_id": 1,
"hostname": "ads.mydas.mobi",
"uri": "/getAd?apid=#{APID}&auid=${DEVICE_MD5}&ua=${USER_AGENT_ENC}&uip=${USER_IP}&age=${AGE}&gender=${GENDER}&zip=${POSTAL_CODE}&lat=${GEO_LAT}&long=${GEO_LON}",
"port": 80,
"is_post": false,
"content": "",
"timeout_ms": 200,
"is_client": false,
"media_subtype": {
"id": 1,
"name": "Standard Banner",
"media_type_name": "Banner",
"media_type_id": 1
},
"last_modified": "2013-07-10 18:57:43",
"macros": [
{
"id": 2,
"template_id": 2,
"code": "APID",
"name": "APID",
"type": "string",
"is_required": true,
"last_modified": "2013-07-02 00:50:53"
}
]
},
"dbg_info": {
"instance": "05.hbapi.sand-08.lax1",
"s1ave_hit": false,
"db": "master",
"awesomesauce_cache_used": false,
"count_cache_used": false,
"warnings": [],
"time": 68.688154220581,
"start_microtime": 1373910064.7161,
"version": "1.13.53.1",
"s1ave_miss": "no_service_index",
"s1ave_lag": 0,
"member_last_modified_age": 1373910064
}
}
}
{code}
Create a request template
Create a JSON file specifying the fields of your request template.
Note
The type_id
field is required on POST
.
For more information about the request template types, see the Creative Custom Request Template Type Service. For documentation of the ad request parameters and macros we support for integration with external mobile ad servers, see Creative Custom Request Template Parameters.
{code}
$ cat create.json
{
"creative-custom-request-template": {
"hostname": "ads.light-vs-wily.com",
"uri": "/a/ads?hid_sha1=${DEVICE_SHA1}&idfa=${DEVICE_APPLE_IDA}&enemy=#{ENEMY}&light_or_wily=#{LIGHT_OR_WILY}&megaman_version=#{MEGAMAN_VERSION}&url=${REFERER_URL_ENC}&ua=${USER_AGENT_ENC}&client-ip=${USER_IP}&country=${USER_COUNTRY}&ll=${JUMPTAP_LAT_LONG_ENC}&mt-age=${AGE}&mt-gender=${GENDER}",
"port": 49995,
"is_post": false,
"content": "",
"timeout_ms": 2,
"is_client": false,
"type_id": 1
}
}
{code}
Make a POST
call to the API with the JSON payload included.
{code}
$ curl -b cookies -X POST -d @create.json https://api.appnexus.com/creative-custom-request-template
{
"response": {
"status": "OK",
"count": 1,
"start_element": 0,
"num_elements": 100,
"creative-custom-request-template": {
"id": 13,
"type_id": 1,
"member_id": 0,
"media_subtype_id": 1,
"hostname": "ads.light-vs-wily.com",
"uri": "/a/ads?hid_sha1=${DEVICE_SHA1}&idfa=${DEVICE_APPLE_IDA}&enemy=#{ENEMY}&light_or_wily=#{LIGHT_OR_WILY}&megaman_version=#{MEGAMAN_VERSION}&url=${REFERER_URL_ENC}&ua=${USER_AGENT_ENC}&client-ip=${USER_IP}&country=${USER_COUNTRY}&ll=${JUMPTAP_LAT_LONG_ENC}&mt-age=${AGE}&mt-gender=${GENDER}",
"port": 49995,
"is_post": false,
"content": "",
"timeout_ms": 2,
"is_client": false,
"media_subtype": {
"id": 1,
"name": "Standard Banner",
"media_type_name": "Banner",
"media_type_id": 1
},
"last_modified": "2013-07-15 19:02:02",
"macros": ""
},
"dbg_info": {
"instance": "07.hbapi.sand-08.lax1",
"s1ave_hit": false,
"db": "master",
"awesomesauce_cache_used": false,
"count_cache_used": false,
"warnings": [],
"time": 67.02995300293,
"start_microtime": 1373914957.1776,
"version": "1.13.53.1",
"s1ave_miss": "no_service_index",
"s1ave_lag": 0,
"member_last_modified_age": 1373914957
}
}
}
{code}
Update a request template
First, create a JSON file with only those parameters you'd like to update.
Note
You must include the id
of the request template being updated.
{code}
$ cat update.json
{"creative-custom-request-template":{"id":13, "type_id":2, "timeout_ms":250}}
{code}
Make the PUT
call, including the JSON update.
Note
In order to make a successful PUT
call, you must do the following:
- Specify the ID of the request template in the JSON file
- Do not add any query string parameters (like
?id=123
) to your request (see the example below).
{code}
$ curl -b cookies -X PUT -d @update.json https://api.appnexus.com/creative-custom-request-template
{code}
Note
A successful PUT
call will not return any JSON response.
Delete a request template
Deleting a request template is straightforward unlike the PUT
call above, you will need to specify the ID of the template you want to delete.
{code}
$ curl -b cookies -X DELETE https://api.appnexus.com/creative-custom-request-template?id=123
{code}