Amazon S3

Sync your user with Audiens

This document will outline the cookie sync procedure for the Audiens platform.


Requirements:

  1. The user must already be already mapped in the Audiens system.

User mapping steps:

  1. Partner's client: The user visit a page where the Audiens pixel is present and a call is made to the endpoint.
  2. Audiens user mapping: Audiens receive the call identify the user.
  3. Audiens reply: Audiens will conclude the redirect flow with an empty 1x1 pixel.

Add the Audiens pixel

To map the user with Audiens, the partner will call the endpoint and initiate the sync procedure.

The URL must respect the following format:

http(s)://data.audiens.com/v1/cookie/match/?audiens_partner={an_id}&audiens_partner_uuid={an_id}

Mandatory parameters:

audiens_partner:
The id of the Partner provided by Audiens during the integration kick-off.
audiens_partner_uuid
The user identification parameter used by the Partner, it will be required to store the matching table on Audiens side.

Examples:

http(s)://data.audiens.com/v1/cookie/match/?audiens_partner=7&audiens_partner_uuid=234
http(s)://data.audiens.com/v1/cookie/match/?audiens_partner=44&audiens_partner_uuid=4578bb95aa2a4

The simplest way to implement the Audiens Mapping Service to an html page is to add an img tag with the correct formatted URL

<img src='http(s)://data.audiens.com/v1/cookie/match/?audiens_partner=7&audiens_partner_uuid=23' />

Audiens identify the user

Audiens will match the audiens_partner_uuid with the internal profiled user.


From this point forward the audiens_partner_uuid can be used to send user data.


Storage on S3 buckets
Send your data to Audiens using AWS S3

Amazon S3 is provided together with the access credentials :

  • Path of the folder bucket.
  • Access Key.
  • Secret Access Key.

Standard format of the data storage URL is:

https://audiens.s3.amazonaws.com/{partner-id}/{date-component}/{filename}

{partner-id}:

Is the partner id provided by Audiens during the integration kick-off.

Examples:

  • 1245
  • 4178

{date-component}

Is the date of files that are provided the split is mandatory as it is used by the system to handle import.

Examples:

  • 2017/01/01
  • 2017/03/10

The date component is in the format yyyy/mm/dd

{filename}

The name of the file that the partner is uploading. The filename can be any format the partner desire. The only restriction is that the extension must be .gz and the file is compressed accordingly.

Examples:

  • 124dfgtre_53ns.gz
  • 20170101_23456789.gz
  • 2017-01-01_11-40_123456.gz

A non mandatory format proposal: yyyymmddhis.gz example 20170101102059.gz

The file must not exceed the 20MB size limit


File content format

The internal file format will need to have the following columns:

user-id,email,email-sha256,phone-number,phone-number-sha256,device-id,segment-id,segment-name

The format is diveded into 2 marco areas (Identifiers, Segment information):

Identifiers:

  • user-id
  • email
  • email-sha256
  • phone-number
  • number-sha256
  • device-id

At least one of the above identifiers is mandatory, the more identifiers you'll provide the higher the match rate can be achieved.

Segment information:

  • segment-id
  • segment-name

Both Segment id and segment name are mandatory


Fields description:

user-id:

Either the customer identification number the CRM id or any unique identifier for the user.

Examples:

  • 457825a1s8
  • 12345

email:

If you cannot provide the hashed version of the email (SHA256) you can just fill this field and we'll take care of the hashing.

Examples:

  • test@gmail.com

email-sha256:

The hashing algorithm you will need to use is SHA256. The email need to be trimmed from any space, lowercase and, validated before hashing.

Examples:

  • 73062d872926c2a556f17b36f50e328ddf9bff9d403939bd14b6c3b7f5a33fc2

phone-number:

If you cannot provide the hashed version of the phone number (msisdn) you can just fill this field and we'll take care of the hashing.

Examples:

  • 394587412547

phone-number-sha256:

The hashing algorithm you will need to use is SHA256. The msisdn needs to be validated before hashing.

Examples:

  • e78c06cadbf1817f1f4184244ccbd8def3a944c1e946b55283f63a9b7b7ba668

device-id:

If available is the mobile phone device id either the ADID or the IDFA. More reference here

Examples:

  • 00000000-89ABCDEF-01234567-89ABCDEF

segment-id (mandatory):

It's a unique segment identifier provided by the data provider. It will be stored in our system as a future mapping. If you need to update the segment just provide the same id and all the new users will be added to the previously created segment.

Examples:

  • 123456
  • A001
  • 123456

segment-name (mandatory):

It's the name of the segment that will be used to produce an entry in the Audiens dashboard and also in the external channels.

Examples:

  • In-market for cars
  • Football lovers
  • High spenders

Some example below:

user-id,email,email-sha256,phone-number,phone-number-sha256,device-id,segment-id,segment-name
457825a1s8,,,,,00040000-00000000-00RRXXXX-XXZZZZZZ,123456,High spenders

In the example above a user-id and a mobile device id is provided, you can provide multiple identifiers but at least one is required.

user-id,email,email-sha256,phone-number,phone-number-sha256,device-id,segment-id,segment-name
,,5dswq2d872926c24se6f17b36f50e328ddf9bff9d403939bd14b6c3b7f5a33fc2,,,,458789,Football lovers
        

In the example above a hashed email is provided, if not already present in our system a new segment with the name Football lovers will be created in our system.

user-id,email,email-sha256,phone-number,phone-number-sha256,device-id,segment-id,segment-name
457825a1s8,,,,,00040000-00000000-00RRXXXX-XXZZZZZZ,123456,High spenders
,,,+394587412547,,,123456,High spenders

In the example above two different users with two different identifiers (mobile id and msisdn) will be added to the High spenders segment. The name and the segment id are always mandatory.