Supported Macros Reference


Overview

Macros enable you to dynamically populate values in your ad-related URLs:

Using macros eliminates the likelihood that a value is mistyped.

If a macro value could potentially contain spaces, the value should be encoded to prevent the URL from breaking. A macro's value can be encoded by wrapping the macro with percentage signs ([%MACRO%]).

For example:

The [APP_NAME] macro value may contain spaces such as My Awesome App. To encode the macro value, use [%APP_NAME%] instead of [APP_NAME]. The macro value will be encoded as: My%20Awesome%20App.


The following tables on this page list all the supported Publica macros.

​​​​


General Macros

Macro

Description

[APP_BUNDLE]

Bundle ID of the app based on the value passed in the app_bundle parameter of the Publica endpoint

For example
samsung.tv.plus.123

[APP_DOMAIN]

Unique identifier for the app domain

For example
mygame.myapp.io

[APP_NAME]

Name of the app based on the value passed in the app_name parameter of the Publica endpoint

For example
My Awesome App

[%APP_NAME%]

Encoded name of the app

For example
My%20Awesome%20App

[APP_STORE_URL]

App store URL

For example
https://www.samsung.com/us/appstore/app/G15147002586

[%APP_STORE_URL%]

Encoded app store URL

For example:
https%3A%2F%2Fwww.samsung.com%2Fus%2Fappstore
%2Fapp%2FG15147002586

[BUYERUID]

Buyer UID

For example:
sample-buyeruid

[CACHEBUSTER]

Random number

For example:
512343819321832

[CHANNEL_LABEL_ID]

The internal ID assigned to a channel label value applied on a channel.

For example:
123

[CONSENT]

GDPR consent string

This dimension is based on the value passed in the consent parameter of the Publica endpoint.

For example:
BOQ7WlgOQ7WlgABABwAAABJOACgACAAQABA

[CONTENT_CAT]

Comma-separated list of IAB Categories

See: OpenRTB, Section 5.1

For example:
IAB8,IAB12-3

[CONTENT_CHANNEL]

Name of the channel

For example:
Publica TV

[CONTENT_CONTEXT]

Type of content being used of consumed by the user in which an ad impression will appear

Possible values:

  • 1: Video
  • 2: Game
  • 3: Music
  • 4: Application
  • 5: Text
  • 6: Other
  • 7: Unknown
[CONTENT_DIST_ID]Unique identifier of the content distributor
[CONTENT_DIST_NAME]Content distributor name
[CONTENT_EPISODE]

Number of the episode

For example:
34

[%CONTENT_GENRE%]

Encoded genre of the content

For example:
Sports (URL encoded)

[CONTENT_ID]

Unique identifier of the content

For example:
123

[CONTENT_KEYWORDS]

Comma-separated keywords associated with the content

For example:
tvshow,comedy

[CONTENT_LANGUAGE]

Content language using ISO-639-1-alpha-2

For example:
fr

[CONTENT_LENGTH]

Length of content in seconds

For example:
342

[CONTENT_NETWORK]Network name of the content
[CONTENT_PROD]

Type of content produced

Possible values:

  • 0: Unknown
  • 1: Professional Produced
  • 2: Prosumer
  • 3: User Generated (UGC)

See: OpenRTB Spec v2.5 - "5.13 Production Quality"

[CONTENT_PRODUCER_ID]Unique identifier of the content producer or originator
[CONTENT_PRODUCER_NAME]

Name of the content producer or originator

For example:
Warner Bros

[CONTENT_RATING]

Rating of the content

For example:
MPAA

[CONTENT_SEASON]

Season of the content

For example:
Season 3

[%CONTENT_SERIES%]

Encoded series of the content

For example:
My%20awesome%20show

[%CONTENT_TITLE%]

Encoded title of the content

For example:
Best%20Episode%20Ever

[COPPA]

Indicates if the request is protected by the Children's Online Privacy Protection Act

Possible values:

  • 0: Requests that are NOT protected by the COPPA

  • 1: Requests that are protected by the COPPA
[COUNTRY]

Three-letter country code of the user

For example:
USA

[CUSTOM_4]
[CUSTOM_5]
[CUSTOM_6]
[CUSTOM_7]
[CUSTOM_8]

Additional targeting parameters used to pass partner-specific information not captured by any other targeting parameter

For example:
If you have distribution markets that each have a unique market ID, you could pass the market ID in Custom 5 to determine which distribution markets are consuming your streams.

[CUSTOM_TARGETING]Returns the value in the custom_targeting parameter of the Publica endpoint.
[DEVICE_LANGUAGE]

Device language

For example:
fr

[DEVICE_MAKE]

Device make

For example:
Samsung

[%DEVICE_MAKE%]

Encoded device make

For example:
Samsung (URL encoded)

[DEVICE_MODEL]

Device model

For example:
Tizen TV 2019

[%DEVICE_MODEL%]

Encoded device model

For example:
Tizen%20TV%202019

[DEVICE_OS]

Device operating system

For example:
Android

[DEVICE_OS_VERSION]

Device operating system version

For example:
2.1

[DEVICE_TYPE]

Device type

For example:
CONNECTED_TV

[%DEVICE_TYPE%]

Encoded device type

For example:
CONNECTED_TV

[DID]

User device ID

In Publica, DID is synonymous with IDFA, IFA, and TIFA.

For example:
ddb9a00f-7806-9973-ba1f-9c4cb0c3c25c

[DMA_CODE]

(US only) Nielsen three-digital DMA code

For example:
803 (Los Angeles)

[DNT]

See: [LIMITED_AD_TRACKING]

[GDPR]

Indicates GDPR acceptance

This dimension is based on the value passed in the gdpr parameter of the Publica endpoint.

Possible values:

  • 0: GDPR does not apply
  • 1: Impression is regulated by GDPR laws
[GENDER]

Gender

Possible values:

  • M: Male
  • F: Female
  • O: Other
[GENRE_ID]Gender ID
[HEIGHT]

Device’s screen height (in px)

For example:
1080

[HOUSE_ADS]

Indicator of whether or not house ads are included

This macro returns the value in the house_ads parameter of the Publica endpoint.

Possible values:

  • 0
  • 1
[IFA_TYPE]

Device ID type

For example:
rida

[IP]

User IP address

For example:
11.11.111.111

[%IP%]

Encoded user IP address

For example:
1111%3Afcc8%3Aa012%3A1111%3A1111%3Ac896%3Ab7d5%3A6ca6

[LIMITED_AD_TRACKING]

Indicates if a user has activated Limited Ad Tracking (LAT) or opted out of targeted advertising

This dimension is based on the value passed in the is_lat parameter of the Publica endpoint.

Possible values:

  • 0: User has NOT opted out targeting advertising
  • 1: User has opted out of targeting advertising
[LIVESTREAM]

Indicator of whether or not content is livestream enabled

Possible values:

  • 0
  • 1
[MAX_AD_DURATION]

Maximum length of an ad in seconds

This value should be smaller than the pod duration.

For example:
30

[MAXBITRATE]

Maximum allowed average kilobits per second

For example:
8000

[MIN_AD_DURATION]

Minimum length of an ad in seconds

For example:
6

[MINBITRATE]

Minimum allowed average kilobits per second

For example:
10000

[%PAGE_URL%]

Encoded page URL

For example:
https%3A%2F%2Fwww.samsung.com

[POD_DURATION]

Length of the ad pod in seconds

For example:
60

[POSITION]

Position

For example:
0-7 (7=Fullscreen)

[PREFERRED_LANGUAGE]

Preferred language

For example:
fr

[RIGHTS_HOLDER]Rights holder
[SCHAIN]

SCHAIN string value

For example:
1.0,1!exchange1.com,1234,1,,,

[SESSION_ID]

Unique identifier for the session

For example:
123

[SITE_ID]

Unique identifier for the channel

For example:
123

[SITE_NAME]Returns the value in the site_name param
[SLOT_COUNT]

Number of ad slots to fill for a pod

For example:
3

[SSAI_ENABLED]

SSAI enabled

For example:
1

[SSAI_VENDOR]

SSAI vendor

[TARGETED_DEVICE]

Targeted device

For example:
Samsung%20TV

[TIMESTAMP]

Unix timestamp

For example:
126345

[%UA%]

Encoded user agent

For example:
Mozilla%2F5.0+%28SMART-TV%3B+Linux%3B+Tizen+4.0%29+AppleWebKit%2F538.1+
%28KHTML%2C+like+Gecko%29+Version%2F4.0+TV+
Safari%2F538.1

[US_PRIVACY]

US Privacy string for CCPA compliance

This macro returns the value passed in the us_privacy parameter of the Publica endpoint.

For example:
1---

[WIDTH]

Device’s screen width (in px)

For example:
1920

[YOB]

User’s year of birth

For example:
1997

​​


Incoming Macros

An incoming macro enables passing content metadata through custom key values to an SSP, but not to a bidder (DSP). 


Macro

Description

[INCOMING_{QUERY_PARAMETER}]

Content metadata passed through custom key values to an SSP

Generally, key-value pairs are inserted into an ext object in which custom is the key to a dictionary of key-value pairs.

This macro should be used when a rule has been set that overrides or omits the value from a supported parameter.

For example:
Consider the following URL:

https://pbs.getpublica.com/v1/s2s-hb?site_id=1243&app_name=AMC&app_bundle=com.amc
&content_title=The+Walking+Dead


For the query parameter content_title, the following passthrough macro is available to capture the query parameter value and pass it to only the SSP:

  • custom:[INCOMING_CONTENT_TITLE] = The Walking Dead


This value is returned through .ext.custom:

"ext": {"custom": {"content_title": "The Walking Dead"}}

​​


Passthrough Macros

A passthrough macro enables passing publisher-defined query parameters that are not supported by other general macros such as [CUSTOM_4][CUSTOM_5][CUSTOM_6][CUSTOM_7], and [CUSTOM_8].

Standard naming conventions apply to publisher-defined query parameters.


Macro

Description

[PT_{QUERY_PARAMETER}]

Single instance of a publisher-defined query parameter and its value

If multiple instances of the same query parameter appear within a URL, only the value of the first instance is retrieved.

For example:
Consider the following URL:

https://pbs.getpublica.com/v1/s2s-hb?site_id=channel_id&app_bundle=your_app_bundle
...&customQueryParam=123&customQueryParam2=abc,def


For the query parameters customQueryParam and customQueryParam2, the following two passthrough macros are available to capture the query parameters and values:

  • [PT_customQueryParam] = 123
  • [PT_customQueryParam2] = abc,def
[PT_{X}_{QUERY_PARAMETER}]

Single instance of a publisher-defined query parameter and its value when multiple instances of that query parameter appear in a URL

The {X} placeholder is replaced by an integer that denotes the order of the query parameter in the URL.

For example:
Consider the following URL:

https://pbs.getpublica.com/v1/s2s-hb?site_id=channel_id&app_bundle=your_app_bundle 
...&customQueryParam=123&customQueryParam=456


There are two instances of customQueryParam. The following two passthrough macros are available to capture the query parameter and values:
  • [PT_1_customQueryParam] = 123
  • [PT_2_customQueryParam] = 456
[PTC_{X}_{QUERY_PARAMETER}]

Single instance of a publisher-defined query parameter and a specific value within a list of values

The {X} placeholder is replaced by an integer that denotes the index of the value in a list from within the URL.

For example:
Consider the following URL:

https://pbs.getpublica.com/v1/s2s-hb?site_id=channel_id&app_bundle=your_app_bundle 
...&customQueryParam2=abc,def&customQueryParam2=qrs,xyz


There are two instances of customQueryParam2 that contain a total of four, comma-separated values: abc, def, qrs, and xyz.  The following four passthrough macros are available to capture the values:
  • [PTC_1_customQueryParam2] = abc
  • [PTC_2_customQueryParam2] = def
  • [PTC_3_customQueryParam2] = qrs
  • [PTC_4_customQueryParam2] = xyz


Post Bid Macros

A post bid macro is a placeholder that can be dynamically populated at the end of the Publica auction.

Macro

Description

[AD_DURATION]

Length in seconds of the winning creative

This macro is currently only supported for direct campaigns and brand safety event trackers.

For example
15

[DEMAND_SOURCE]

Post-auction value to identify demand partner of the won impression

For example:
appnexus

[TRACKERUUID]

Unique ID generated for impression events

For example:
b16a3b5b-5bb9-45f8-8f58-5027573cd66b

​​



Table of Contents