{"_id":"565e7928f76b8d0d005541bf","user":"55de06e19db51a0d0064947d","__v":1,"parentDoc":null,"project":"55de06fa57f7b20d0097636b","category":{"_id":"5644cf437f1fff210078e690","__v":4,"project":"55de06fa57f7b20d0097636b","version":"55de06fa57f7b20d0097636e","pages":["5644cfd9d608df0d00d2699a","5644d21a98da41190099f28d","5644e228d608df0d00d269c8","565e7928f76b8d0d005541bf"],"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-11-12T17:41:23.898Z","from_sync":false,"order":5,"slug":"rest-api","title":"Pixel Audiences and Pixel REST API"},"version":{"_id":"55de06fa57f7b20d0097636e","project":"55de06fa57f7b20d0097636b","__v":14,"createdAt":"2015-08-26T18:35:38.642Z","releaseDate":"2015-08-26T18:35:38.642Z","categories":["55de06fb57f7b20d0097636f","55f1962e3936d52d00fb3c8f","55f1970339e3e8190068b2b8","55f1970d229b772300779a1f","55f1971cfd98c42300acc605","55f1d5c7fd98c42300acc69f","563cbfe4260dde0d00c5e9d4","5644cf437f1fff210078e690","57dc1bbd3ed3450e00dc9ea7","58a600a2243dd30f00fd8773","58ed1bdc068f780f00f64602","58f13b3a4f0ee50f00e24e81","58f173f792f9020f009cad16","591b42f8e633fd0f00077c5a"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-12-02T04:52:56.788Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"Pixel Audiences allow you to submit data about devices and the events they perform to PushSpring.  You can use this audience as part of an ad campaign to track events like impressions, clicks, and conversions.\n[block:api-header]\n{\n  \"title\": \"Audiences and Audience Keys\"\n}\n[/block]\nEach Audience represents a group of devices that are related somehow.  For instance, you might create a new Audience to represent the devices associated with a particular advertising campaign or even a separate Audience for each of the creative flights of a given campaign.  You will need to generate a new PushSpring PIxel Audience for each separate Audience you wish to send data about.\n[block:api-header]\n{\n  \"title\": \"Generating and using a Pixel Audience\"\n}\n[/block]\nDuring the first phase of the rollout of Pixel Audiences, you will need to request each audience from your PushSpring account representative.  PushSpring can pre-generate as many pixels as you need, and we will shortly be delivering a self-service UI through which you can create your own Pixel Audiences.\n\nOnce the pixel is generated, you will add it to your campaign creative as you do with any other third party pixel.  During this process, you will need to ensure you have edited the pixel to include your DSP's or Ad Server's macro for IDFA/Android Ad ID.  As an example, you might receive a pixel that looks like this:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"https://pixel.pushspring.com/audience/device/add?token=PIXEL_ID_FROM_PUSHSPRING&id={{IDFA_AD_ID_MACRO}}&event=impression\",\n      \"language\": \"http\"\n    }\n  ]\n}\n[/block]\nYou _MUST_ replace the `{{IDFA_AD_ID_MACRO}}` with the proper macro used for your DSP or Ad Server in order to send the IDFA or Google Advertising ID of the device you want to add to the Audience.\n\nFor example, if you are using the DFP ad server, you would replace `{{IDFA_AD_ID_MACRO}}` with `%%ADVERTISING_IDENTIFIER_PLAIN%%` as we have below:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"https://pixel.pushspring.com/audience/device/add?token=PIXEL_ID_FROM_PUSHSPRING&id=%%ADVERTISING_IDENTIFIER_PLAIN%%&event=impression\",\n      \"language\": \"http\"\n    }\n  ]\n}\n[/block]\nIt is also important that you not modify the value of the `token` parameter, as that uniquely identifies each Pixel Audience.\n[block:api-header]\n{\n  \"title\": \"Redirection after firing the Pixel\"\n}\n[/block]\nIf you plan to use your Pixel Audience as part of an <img> tag, you might need it to redirect to a transparent 1x1 image to avoid browser errors.  If you include the additional parameter `r` on the end of the pixel URL, you can specify a URL that PushSpring will `302 Redirect` to after firing the pixel.  If you include the `r` parameter but do not specify a URL, PushSpring will `302 Redirect` to our 1x1 transparent image by default.  As an example:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"https://pixel.pushspring.com/audience/device/add?token=PIXEL_ID_FROM_PUSHSPRING&id={{IDFA_AD_ID_MACRO}}&event=impression&r\",\n      \"language\": \"http\"\n    }\n  ]\n}\n[/block]\n...will cause PushSpring to redirect to our default 1x1 transparent image.  If instead you wish to redirect to another location, simply specify it as an URLEncoded parameter:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"https://pixel.pushspring.com/audience/device/add?token=PIXEL_ID_FROM_PUSHSPRING&id={{IDFA_AD_ID_MACRO}}&event=impression&r=https%3A%2F%2Fwww.google.com\",\n      \"language\": \"http\"\n    }\n  ]\n}\n[/block]\n...which will cause the PushSpring server to redirect to that URL instead.\n[block:api-header]\n{\n  \"title\": \"Standard Events Supported\"\n}\n[/block]\nWhen you generate a Pixel Audience, you will be given versions that can be used to track impressions, clicks, and conversions for the devices added to the Audience.  The `event` parameter specifies the event associated with this firing of the pixel.  There is special support in the PushSpring Audience Console for working with these most common event names:\n\n`impression`\n`click`\n`conversion`\n\nAdvanced users can specify any event names they wish in the `event` parameter.  These events then become available in the PushSpring Audience Console for segmentation.\n[block:api-header]\n{\n  \"title\": \"Pixel Audience Parameter Reference\"\n}\n[/block]\nWe support both a GET and a POST when working with a Pixel Audience.\n\nThe GET operation is vulnerable to caching so it is recommended that you include a cache busting parameter in each request.  Most ad servers and DSPs have a \"cache buster\" macro that you can use to insert a random value into the link. We recommend a parameter `cb` for this purpose.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Parameter\",\n    \"h-1\": \"Required\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"token\",\n    \"0-1\": \"Y\",\n    \"0-2\": \"Unique id for the Audience associated with this pixel.  **Do Not Modify**\",\n    \"1-0\": \"id\",\n    \"1-1\": \"Y\",\n    \"1-2\": \"Advertising Identifier for the device.  **You must replace the value of this parameter with your DSP or Ad Server Macro associated with Advertising Identifiers (IDFA or Google Advertising ID)**.  Please contact PushSpring if you need help with this.\",\n    \"2-0\": \"event\",\n    \"2-1\": \"N\",\n    \"2-2\": \"Event to associate with this device for this pixel firing.  Standard events are `impression`, `click`, and `conversion`.  You may also send any other event names that are useful for your campaign.  **Note:** if you do not supply an event parameter, PushSpring will assume the event is an `impression` by default.\",\n    \"3-0\": \"r\",\n    \"3-1\": \"N\",\n    \"3-2\": \"The url to redirect to.  Useful if you embed this call in an `<img>` tag.  Expects a fully qualified. URL encoded uri that can be redirected to.  Server will return a 302 redirect to the client with its Location set to this URI.\",\n    \"4-0\": \"cb\",\n    \"4-1\": \"N\",\n    \"4-2\": \"Allows you to include a \\\"cache buster\\\" or other random number to defeat any HTTP caching that may interfere with direct communication of this pixel to PushSpring.\"\n  },\n  \"cols\": 3,\n  \"rows\": 5\n}\n[/block]","excerpt":"","slug":"introduction","type":"basic","title":"Pixel Audience Introduction"}

Pixel Audience Introduction


Pixel Audiences allow you to submit data about devices and the events they perform to PushSpring. You can use this audience as part of an ad campaign to track events like impressions, clicks, and conversions. [block:api-header] { "title": "Audiences and Audience Keys" } [/block] Each Audience represents a group of devices that are related somehow. For instance, you might create a new Audience to represent the devices associated with a particular advertising campaign or even a separate Audience for each of the creative flights of a given campaign. You will need to generate a new PushSpring PIxel Audience for each separate Audience you wish to send data about. [block:api-header] { "title": "Generating and using a Pixel Audience" } [/block] During the first phase of the rollout of Pixel Audiences, you will need to request each audience from your PushSpring account representative. PushSpring can pre-generate as many pixels as you need, and we will shortly be delivering a self-service UI through which you can create your own Pixel Audiences. Once the pixel is generated, you will add it to your campaign creative as you do with any other third party pixel. During this process, you will need to ensure you have edited the pixel to include your DSP's or Ad Server's macro for IDFA/Android Ad ID. As an example, you might receive a pixel that looks like this: [block:code] { "codes": [ { "code": "https://pixel.pushspring.com/audience/device/add?token=PIXEL_ID_FROM_PUSHSPRING&id={{IDFA_AD_ID_MACRO}}&event=impression", "language": "http" } ] } [/block] You _MUST_ replace the `{{IDFA_AD_ID_MACRO}}` with the proper macro used for your DSP or Ad Server in order to send the IDFA or Google Advertising ID of the device you want to add to the Audience. For example, if you are using the DFP ad server, you would replace `{{IDFA_AD_ID_MACRO}}` with `%%ADVERTISING_IDENTIFIER_PLAIN%%` as we have below: [block:code] { "codes": [ { "code": "https://pixel.pushspring.com/audience/device/add?token=PIXEL_ID_FROM_PUSHSPRING&id=%%ADVERTISING_IDENTIFIER_PLAIN%%&event=impression", "language": "http" } ] } [/block] It is also important that you not modify the value of the `token` parameter, as that uniquely identifies each Pixel Audience. [block:api-header] { "title": "Redirection after firing the Pixel" } [/block] If you plan to use your Pixel Audience as part of an <img> tag, you might need it to redirect to a transparent 1x1 image to avoid browser errors. If you include the additional parameter `r` on the end of the pixel URL, you can specify a URL that PushSpring will `302 Redirect` to after firing the pixel. If you include the `r` parameter but do not specify a URL, PushSpring will `302 Redirect` to our 1x1 transparent image by default. As an example: [block:code] { "codes": [ { "code": "https://pixel.pushspring.com/audience/device/add?token=PIXEL_ID_FROM_PUSHSPRING&id={{IDFA_AD_ID_MACRO}}&event=impression&r", "language": "http" } ] } [/block] ...will cause PushSpring to redirect to our default 1x1 transparent image. If instead you wish to redirect to another location, simply specify it as an URLEncoded parameter: [block:code] { "codes": [ { "code": "https://pixel.pushspring.com/audience/device/add?token=PIXEL_ID_FROM_PUSHSPRING&id={{IDFA_AD_ID_MACRO}}&event=impression&r=https%3A%2F%2Fwww.google.com", "language": "http" } ] } [/block] ...which will cause the PushSpring server to redirect to that URL instead. [block:api-header] { "title": "Standard Events Supported" } [/block] When you generate a Pixel Audience, you will be given versions that can be used to track impressions, clicks, and conversions for the devices added to the Audience. The `event` parameter specifies the event associated with this firing of the pixel. There is special support in the PushSpring Audience Console for working with these most common event names: `impression` `click` `conversion` Advanced users can specify any event names they wish in the `event` parameter. These events then become available in the PushSpring Audience Console for segmentation. [block:api-header] { "title": "Pixel Audience Parameter Reference" } [/block] We support both a GET and a POST when working with a Pixel Audience. The GET operation is vulnerable to caching so it is recommended that you include a cache busting parameter in each request. Most ad servers and DSPs have a "cache buster" macro that you can use to insert a random value into the link. We recommend a parameter `cb` for this purpose. [block:parameters] { "data": { "h-0": "Parameter", "h-1": "Required", "h-2": "Description", "0-0": "token", "0-1": "Y", "0-2": "Unique id for the Audience associated with this pixel. **Do Not Modify**", "1-0": "id", "1-1": "Y", "1-2": "Advertising Identifier for the device. **You must replace the value of this parameter with your DSP or Ad Server Macro associated with Advertising Identifiers (IDFA or Google Advertising ID)**. Please contact PushSpring if you need help with this.", "2-0": "event", "2-1": "N", "2-2": "Event to associate with this device for this pixel firing. Standard events are `impression`, `click`, and `conversion`. You may also send any other event names that are useful for your campaign. **Note:** if you do not supply an event parameter, PushSpring will assume the event is an `impression` by default.", "3-0": "r", "3-1": "N", "3-2": "The url to redirect to. Useful if you embed this call in an `<img>` tag. Expects a fully qualified. URL encoded uri that can be redirected to. Server will return a 302 redirect to the client with its Location set to this URI.", "4-0": "cb", "4-1": "N", "4-2": "Allows you to include a \"cache buster\" or other random number to defeat any HTTP caching that may interfere with direct communication of this pixel to PushSpring." }, "cols": 3, "rows": 5 } [/block]