Summary

Streaming segments are used to deliver user segment membership in real-time for data that is managed offline or via an external system that does not contain the Audience Studio Control Tag or mobile SDK. Streaming segments can be combined with real-time offsite activation partners to support real-time audience targeting use cases, such as retargeting, global frequency management (suppression), sequencing and more.

Streaming Segments are for off-site activation only.

This document describes the prerequisites and steps to create, deliver user segment membership and activate to make available in partner execution systems.

Prerequisites

The following are prerequisites: to consider when creating streaming segments:

Streaming Segments must be configured for your Organization and you must plan to send delete signals or use the default 30 day ttl (Device expiry timeframe) for streaming segments
API key to create streaming segments via API
Audience Studio account access (username and password) for API authentication (note: these are case sensitive)
User match to support customerid to kuid lookup
Activation partners enabled in Segment Management via Partner Management to configure delivery of data to external execution systems
Inform your Success Manager of the expected volume of data

Implementation

Create a Streaming Segment

A streaming segment may be created by sending the following parameters as part of the API call. This process will create the initial segment shell for user segment mapping to be provided. The segment shell should be created at least 15 minutes prior to sending segment membership data.

"name" : Name of streaming segment – this must be unique and is mandatory
"type", "category", "sub_category", "description" : Optional organizational descriptions

Example API

Note: <API_KEY> would be replaced with your API Key

curl --user <username>:<passwd> --dump-header - -H "Content-Type: application/json" --data '{"name": "segment_a"}' https://console.krux.com/api/v1/audience_streaming/create_streaming_segment/?api_key=<API_KEY>

HTTP/1.1 201 OK

...

{"message": "Streaming Segment has been created", "segment": {"category": "", "description": "", "id": 391107, "name": "streaming_test_segment", "organization_uuid": "abc35346-2db7-45d7-a86d-a3ea84e4fffe", "segment_type": "streaming", "segment_uuid": "ABmlEyGK", "segment_uuid_long": "abk1vq47g", "sub_category": "", "type": ""}}

Deliver User Segment Membership

User segment membership may be delivered using the segment.gif endpoint. The following are descriptions of the parameters to include.

_kpid : organization_uuid (organization_uuid is returned in response to streaming segment creation api)
segs: comma delimited user segment long uid list (Segment long uid is returned in response to streaming segment creation api)
fpuid: SINGLE first party uid (fpuid or _kuid)
_kuid: Krux UID or MAID (fpuid or _kuid)
action: add to add user to segment or delete to remove user from segment. Default = add

Either fpuid or _kuid may be provided. If _fpuid is provided, users will be matched based on user match lookup. Otherwise, kuid will be used and doesn't require lookup.

The return code is expected to be "204" if the endpoint is accessible.

Please be aware of the character limitations associated with passing data via http get url. As referenced in the HTTP 1.1 specification in an extract of chapter 3.2.1:

Note: Servers ought to be cautious about depending on URI lengths above 255 bytes, because some older client or proxy implementations might not properly support these lengths

example request:

https://beacon.krxd.net/segment.gif?fpuid=e46bd0dc-9e6f-42ec-8b72-1d988d329ca7&_kpid=ad135346-2db7-45d7-a86d-a3ea84e4ffle&segs=nhev8uwwf&action=add

Activate Streaming Segment

To activate a streaming segment to be sent to a partner, login to Manage Segments, edit the segment, and select the desired activation partners. Note: Bulk edit options are available for enabling or disabling activation partners for multiple segments.

Manage in Partner System

Once a streaming segment has been created and activated for partners, the segments should be made available in the partner system to be applied to campaigns.

Data is sent to partners via a constant stream if the partner supports real-time and has been enabled as a real-time partner in Audience Studio. Other partner data is still sent in batch daily. Partner Management data is updated on a daily basis regardless of real-time or batch sending.

Note: Data availability in partner systems varies by partner and may need to be addressed directly with the partner if there is a delay between data sent from Audience Studio and availability in execution system. Data sent to activation partners is updated daily in the Activation > Partner Management section of Audience Studio.

Segment Population

However, in order to deduplicate unique users for each segment, segment population needs to be aggregated periodically for reference within Audience Studio. This process runs every 12 hours.

Segments: Streaming Segments Implementation