{"_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":"The PushSpring Audience Pixel allows you to submit data about devices and the events they perform to PushSpring.  You can use this pixel 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 Audience Pixel for each separate Audience you wish to send data about.\n[block:api-header]\n{\n  \"title\": \"Generating and using an Audience Pixel\"\n}\n[/block]\nDuring the first phase of the rollout of Audience Pixels, you will need to request pixels 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 Audience Pixels.\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 an Audience Pixel that looks like:\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 the Audience associated with this Audience Pixel.\n[block:api-header]\n{\n  \"title\": \"Redirection after firing the Audience Pixel\"\n}\n[/block]\nIf you plan to use the Audience Pixel 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 an Audience Pixel, 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\": \"Audience Pixel Parameter Reference\"\n}\n[/block]\nWe support both a GET and a POST when working with an Audience Pixel.\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


The PushSpring Audience Pixel allows you to submit data about devices and the events they perform to PushSpring. You can use this pixel 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 Audience Pixel for each separate Audience you wish to send data about. [block:api-header] { "title": "Generating and using an Audience Pixel" } [/block] During the first phase of the rollout of Audience Pixels, you will need to request pixels 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 Audience Pixels. 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 an Audience Pixel that looks like: [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 the Audience associated with this Audience Pixel. [block:api-header] { "title": "Redirection after firing the Audience Pixel" } [/block] If you plan to use the Audience Pixel 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 an Audience Pixel, 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": "Audience Pixel Parameter Reference" } [/block] We support both a GET and a POST when working with an Audience Pixel. 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]