Information

Title	Cookie targeting

URL Name	Cookie-targeting

Details

Article Body

About cookie targeting

With Equativ's cookie targeting, you can

store and update data in cookies (in end-users' browsers)
target insertions to the presence/absence of data stored in cookies

Use cases

a behavior targeting vendor stores user profile data in cookies; with cookie targeting, you can target insertions to this profile data.
a retargeting vendor needs to "tag" users who visited a site; with cookie targeting you can target insertions to these tagged visitors.
you need to tag users who have signed up on your site; with cookie targeting you can target these users.

Key concepts

Cookie

Cookies are text files containing stored data. A cookie has a name, a content with stored data and a time to live. Equativ supports 2 main cookie types: partner cookie and the comp cookie.

Cookie request

The cookie request is a call to Equativ which passes the data to be stored (in key=value format) and information about the time to live of the cookie.

Cookie targeting

Cookie targeting allows you to restrict insertion delivery to display the ad of the insertion only if specific data is present/absent in the cookie.

Partner cookie

With the partner cookie, you can store different sets of data in separate cookies (with unique cookie names); each cookie request fully overwrites any existing data in the cookie

Comp cookie

With the comp cookie, you store all the data in one single cookie which has the name comp; you can then store, delete and update data in this cookie

Cookie targeting using keyword targeting UI

Data passed via cookies and data passed via keywords (target parameter in ad calls) are processed the same way. To define cookie targeting criteria, simply use the keyword targeting UI as explained here.

Targeting string (key=values)

The targeting string contains the data to be stored in the cookie. It is a list (sequence) of key=values.

multiple key=values items must be separated by semicolons: key1=value1;key2=value2
the key part must not contain the characters ";" or "="
the value part must not contain the character ";"
all other Unicode characters are allowed

Response to cookie requests

When receiving the cookie request, Equativ will

store the cookie with the appropriate key=values and specified time to live (if applicable)
return the HTTP status code 200 (OK); this is the only status code used; there is no notification in case of erroneous requests (e. g. parameters missing or formatted incorrectly)

Writing data in a partner cookie

With the partner cookie, you can store different sets of data in separate cookies. Typically, each partner cookie (with its stored data), represents a partner (e. g. a behavioral targeting vendor, retargeting vendor etc.).

each partner cookie has a unique name
the partner’s name is part of the cookie name (in the form of the hash of the partner name specified in the cookie request)
each cookie request fully overwrites any existing data in the cookie: removing/adding individual key=values is not supported in partner cookies!

Cookie request format

(http|https)://<smartAdServerDomain>/diffx/track/partner?partnername=<name>&value=<targetingString>&expdate=<daysTillExpiry>

Note: For a secure call, simply replace http by https.

Parameters

Name	Mandatory	Description	Default value
partnername	yes	The partner’s name	n/a
value	yes	The targeting string (containing the key=values) to be stored for the partner	n/a
expdate	no	The time to live in days to be assigned to the partner cookie.	30

Name of stored cookie

partner-<hash>

where <hash> is a parameter computed from the partner name

Example

http://diff.smartadserver.com/diffx/track/partner?partnername=mypartnercookie&value=mykey=myvalue

Writing, clearing and updating data in the comp cookie

With the comp cookie, you store all the data in one single cookie which has the name comp. You can wipe all key=values as well as update individual key=values (delete/add).

Time to live (TTL)

The time to live (TTL) specifies the time until the comp cookie dies.

parameter name: ttl=
the value must be a positive number; example: ttl=5
default time unit: days
TTL can be used together with the time unit parameter (tu=) in order to change the time unit (see next paragraph)
if unspecified, the TTL is 30 days
maximum TTL is 30 days

Time unit

Optionally, you can can pass the time unit parameter (tu=) together with the TTL parameter (ttl=) in order to specify a time unit other than the default days.

Possible values:
- seconds
- minutes
- hours
- days
Default value: days

Writing data

Cookie request format

http://diff.smartadserver.com/profile/write?nwid=<networkId>&value=<targeting>&ttl=<ttl>&tu=<timeUnit>

Effect
This cookie request fully overwrites any existing data in the comp cookie and stores the new key=values.

Parameters

Name	Mandatory	Description	Default value
nwid	yes	The network ID (represents the ID of your account at Equativ)	n/a
value	yes	The targeting string (containing the key=values) to be stored	n/a
ttl	no	The time to live to be assigned to the cookie. Maximum TTL is 30 days.	30
tu	no	The time unit to be used for the time to live; only when ttl is specified; possible values: seconds, minutes, hours, days	days

Name of stored cookie

comp-<networkId>

Example

http://diff.smartadserver.com/profile/write?nwid=73&value=mykey=myvalue&ttl=10&tu=days

Clearing data

Cookie request format

/profile/clear?nwid=<networkId>

Effect
This cookie request clears (wipes) any existing data in the comp cookie.

Parameters

Name	Mandatory	Description	Default value
nwid	yes	The network ID (represents the ID of your account at Equativ)	n/a

Name of stored cookie

comp-<networkId>

Example

http://diff.smartadserver.com/profile/clear?nwid=73

Updating data

Cookie request format

/profile/update?nwid=<networkId>&set=<targeting>&delete=<keywords>&ttl=<ttl>&tu=<timeUnit>

Effect
This cookie request removes and stores data (key=values) in the comp cookie. It is the most advanced operation since it allows for granular and complex operations.

Rules

you cannot use duplicate keys
when processing the call, the delete operation is always applied before the set operation; thus, if a keyword is specified in both the set and the delete parameter, only the data of the set parameter will be ultimately stored in the cookie

Parameters

Name	Mandatory	Description	Default value
nwid	yes	The network ID (represents the ID of your account at Equativ)	n/a
set	no*	The targeting string (containing the key=value items) to be added to the existing data in the comp cookie	n/a
delete	no*	The list of keywords to be removed from the previous targeting, separated by semicolons**	n/a
ttl	no	The time to live to be assigned to the cookie. Maximum TTL is 30 days.	30
tu	no	The time unit to be used for the time to live; only when ttl is specified, possible values: seconds, minutes, hours, days	days

* At least one of the set and delete parameters must be specified for the request to be valid.
** Example: Assume that the currently stored targeting is: “name=bob;color=green;car=big”; if the delete parameter value is set to “name;color”, the remaining stored targeting will be: “car=big”;

Name of stored cookie

comp-<networkId>

Examples

http://diff.smartadserver.com/profile/update?nwid=73&set=name=bob;color=green;car=big&ttl=10&tu=days
http://diff.smartadserver.com/profile/update?nwid=73&delete=name;color

Notes