Platform Segments Guide

Avatar
Richard Weber
Follow

Introduction

Audience Studio is technology agnostic and continues to support customers who use different forms of analysis, both offline and online.

The following guide is for users that perform their own offline analysis and wish to create new segments via the API. These platform segments can be comprised of 1) Krux User IDs (KUIDs), 2) Mobile IDs or 3) first-party IDs that have been matched with KUIDs.

Setup

Client to provide Audience Studio to provide
Name & Location of user-data file transfer Client’s account API key, S3 credentials and location
Timing
When transfer will take place (and frequency)		  daily hour in UTC time to process
Naming Convention
Please suffix file name with date		  

First, platform segments are created via the API as described below.

Next, the user-data file must be uploaded so Audience Studio can process and associate the users with the appropriate platform segments.

Create Platform Segments in the UI

Users can create platform segments directly in the UI. Click on "+ New Segment" and select "Platform" (screenshot below) as an option and go through the usual workflow of naming and creating a segment. Because platform segments are essential "shell" segments, you will not define any rules or use attributes in creating them. 

Following up you need to go to Manage -> Data Capture Sources and create a pipeline to import the provided User-data File for Platform Segments.

Note: the connector should be configured as Krux Format as it follows the standard file format for Platform Segments.

For more information on how to do this, please refer to Self Serve First Party Imports.

If you do not see an option for "Platform" type segments please contact your Salesforce Audience Studio representative to get this provisioned. 

Create Platform Segments via API

Platform segments are not rule-based and therefore no rules will be shown in the UI. Users for these platform segments can either be loaded from external systems or determined via external means.

A platform segment can be created by sending the following parameters as part of the API call. Use the same username/password as for Konsole.

  1. "name" : Name of platform segment – this must be unique and is mandatory.
  2. "type", "category", "sub_category", "description" : Optional organisational descriptions.

Example API

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

HTTP/1.1 200 OK
...
{"message": "Segment has been created", "segment": {"category": "", "description": "", "id": 16681, "name": "segment_a", "segment_uuid": "I1p1W5QN", "segment_uuid_long": "n21l7tjtr", "sub_category": "" , "type": "" }}

An alternative free API tool is Postman (https://www.getpostman.com/). Create your platform segments with a POST request with the same JSON payload in above and user authentication as your console account.

Create Segments Using Other Segments

A new segment can be created using existing segments. To create a segment, a POST request needs to be sent. In the request, the following is required:

  1. "name" : Specifies the segment name
  2. "operator" : OR|AND. Specifies the operator that connects the segments.
  3. "rules" : Specifies the rules.
  4. "segments" : List of segment IDs that must be combined to create a new segment.

Example API for creating a new segment based on segments 234 and 235 which must already exist:

curl --user <username>:<passwd> --dump-header - -H "Content-Type: application/json" --data '{"name": "segment_b", "operator": "OR", "rules" : {"segment" : [234, 235]} }' https://console.krux.com/api/v1/audience/create_segment/?api_key= <API_KEY>

HTTP/1.1 200 OK
...
{"message": "Segment has been created" "segment": {"category": "", "description": "", "id": 16681, "name": "segment_b", "segment_uuid": "I1p1W5QN", "segment_uuid_long": "n21l7tjtr", "sub_category": "" , "type": "" }}

Remove Platform Segments

Platform segments can be removed using APIs as well. A platform segment can be deleted by sending a DELETE request with the following parameter as part of the API call:

  1. "segment_uuid" : UUID of the segment that needs to be removed. This is mandatory and is the same as the "segment_uuid" parameter which is returned when a platform segment is created.

Example API

curl --user <username>:<passwd> -H "Content-Type: application/json" -X DELETE 'https://console.krux.com/api/v1/audience/remove_platform_segment/?api_key=<API_KEY>&segment_uuid=JUd4YrAR'

HTTP/1.1 200 OK
...
{"message": "Segment JUd4YrAR has been deleted"}

Upload User-data File for Platform Segments

An Audience Studio Amazon S3 bucket can be supplied to upload files daily.  For example  s3://krux-partners/client-NAME/uploads/platform_seg/YYYY-MM-DD/

The user data file can be gzipped or uncompressed if the size is manageable. Files equal to or greater than 1GB should be compressed with gzip.

The standard file format is:

ID^segment_uuid_long_1
ID^segment_uuid_long_2
ID^segment_uuid_long_3

Note: ID is either: Audience Studio browser ID, mobile ID (IDFA or Android Ad ID), or your first party ID. The segment_uuid_long field is the ID returned in the API call used to create the segment shell.

Each row should contain only ID to 1 segment ID.

Segments with Hashed Email IDs 

For Hashed Email (HEM) IDs, Audience Studio supports three hashing algorithm types: SHA256, SHA1, and MD5.

You will choose a specific hashing encryption algorithm (SHA256, SHA1, and MD5) while onboarding and we expect that you will use the same hashing algorithm, along with your ID, when you create and upload segments.

The standard file format for segments with HEM-based IDs is:

hem:hemType:hashed_email^segmentId

When we mention 'hashed_email' above, we mean 'hashed email address'.

The following example includes 3 sample segments (one showing each encryption algorithm) that can be used for an email ID "test_email@gmail.com" that we are uploading for a hypothetical segment "abc123xyz".

SHA256:

hem:sha256:88d5400a684fd68bcdea389a5fd4143c763fa2f292b02aab489d231fe0052067^abc123xyz

SHA1:

hem:sha1:ada6c08cad5c5e3c1a47251d2232f4c967c7feb1^abc123xyz

MD5:

hem:md5:e78931f87a8840efbad464db95e4d40b^abc123xyz


Overwrite (Full Refresh)

If the user membership per segment does NOT change from day to day, do not upload the segment again.  The segment's population will not change.  

If the user membership per segment DOES change, upload the segment again with ALL users.  For example

  • Day 1 - segment A size = 100 - upload 100 ids to segment A
  • Day 2 - segment A size = 100 - do not upload any users for segment A
  • Day 3 - segment A size = 200 - upload all 200 ids to segment A

*No look back is required.

 Append (Incremental)

The ability to provide smaller files that add onto the existing Platform segment. 

  • Day 1 - segment B size = 50 upload 50 ids to segment B with a lookback of 10 days
  • Day 2 - segment B size = 75 upload 25 new ids to segment B
  • Day 3 - segment B size = 100 upload 25 new ids to segment B
  • Day 11 - no new kuids added, segment B size = 50. IDs from Day 1 drop out of segment B due to 10 day look back

*Look back configuration is required. 

 Overwrite (Full Refresh) and Append (Incremental)

The ability to use both forms is possible. Please work with support to verify your setup is correct. Two self-service import jobs should be configured. One for Overwrite and one for append, each import job will have its own file drop location. 

Example:

 s3://krux-partners/client-NAME/uploads/platform_seg/full/YYYY-MM-DD/ and s3://krux-partners/client-NAME/uploads/platform_seg/incr/YYYY-MM-DD/

Scenario 1:

  • Day 1 - segment B size = 50 append 50 new ids to segment B with a look back of 10 days
  • Day 2 - segment B size = 75 append 25 new ids to segment B
  • Day 3 - segment B size = 100 append 25 new ids to segment B
  • Day 4 - segment B size = 100 full refresh of 100 ids
  • Result: The segment is wiped out. Segment B contains the full refresh of Day 4.

Scenario 2:

  • Day 1 - segment B size = 100 full refresh of 100 ids
  • Day 2 - segment B size = 125 append 25 new ids to segment B, look back 10 days
  • Day 3 - segment B size = 150 append 25 new ids to segment B, look back 10 days
  • Day 4 - segment B size = 175 append 25 new ids to segment B, look back 10 days
  • Result: The segment contains the full refresh data and the additions of days 2, 3, and 4. The look back of 10 days does not change segment size because we are only on day 4.

Scenario 3:

  • Day 1 - segment B size = 100 full refresh of 100 ids
  • Day 9 - segment B size = 125 append 25 new ids to segment B, look back 10 days
  • Day 10 - segment B size = 150 append 25 new ids to segment B, look back 10 days
  • Day 11 - segment B size = 75 append 25 new ids to segment B, look back 10 days
  • Result: The segment contains the updates of day 9, 10, and 11. Segment B does not include the users from day 1 because look back window is 10 days. 

 Overwrite (Full Refresh) Expiry policy

Users do not expire out of the Audience Studio platform segments.  For example, if you upload a segment with 1MM users, no users will drop out, unless a new upload removes the users.

 Append (Incremental) Expiry policy

Users expire out of the Audience Studio platform segments based on the look back window configured.  For example, if you upload a segment with 1MM users on day 1 with a look back window of 10 days, users will drop out of segment on day 11.

 Consent

Important:  If you wish to pass through a corresponding file for consent to provide consent signals for the devices included in your first party import file, you must drop the consent file three days prior to dropping the first party import file on S3.  This way we can guarantee that the consent for the devices will be ingested prior to ingesting records from the import file, and that we can correctly gate data collection and other data activities accordingly.  

 

Need Help?

If you need help with Audience Studio API Platform Segments, don't hesitate to contact the Salesforce Audience Studio Solutions team at kruxhelp@krux.com.

Have more questions? Submit a request

0 Comments

Article is closed for comments.