Outbound
The DMP is integrated with various advertising and marketing platforms. Custom and Lookalike Audiences are all processed in real-time, meaning the user is send to the 3rd party execution platform the moment he fits the criteria of the audience. The process below outlines how to integrate with the Mapp DMP and its real-time capabilities.
| Contents of the Table |
|---|
Use Cases
Below a couple of use cases for an integration between our DMP and a 3rd party (execution) platform.
- Custom Audiences: Push Custom Audiences to the integrated execution platform to target specific users and show them relevant advertisements or content across the various channels.
- Lookalike Audiences: Push Lookalike Audiences to the integrated execution platform to target specific users and show them relevant advertisements or content across the various channels.
Process
The process of setting up a new integration for audience building purposes consists of three main steps.
User Syncing
Mapp initiates the cookie syncing for the users with the 3rd party system. Typically the process is that every now and then (e.g. a few days) Mapp calls out to the 3rd party system to request their cookie ID for a given user. This is a redirect happening on the client-side while the browser is executing on our tracking pixel(s). The process looks as follows:
- Setup the appropriate user sync template: https://api.thirdparty.com/sync?out=https://go.flx1.com/uid?userid=[[USERID]]&pl=<platformId:integer>&plsec=<secureToken:string>.
The 3rd party system then receives this request, replaces the macro "[[USERID]]" with their user ID and redirects back to the out URL. The secure token for the "plcsec" parameter is provided by Mapp and will be validated automatically.
- The redirect initiates a call to our mapping table to store the appropriate user ID: https://go.flx1.com/uid?userid=abcdef123&pl=99999&plsec=verysecure.
There is also the possibility to use signed syncing requests, where a SHA1-HMAC will be computed based on a shared secret, not exposing the secret and making it impossible to tamper with the data being exchanged. If you are not familiar with this, it means that it's likely not relevant to your business.
Segment Creation
Mapp sends the segment name by an API call and will receive the 3rd party segment ID back from the 3rd party system.
- Example request based on basic authentication (we also support other authentication requests): curl -XPOST -u foo:bar https://api.third-party.com/v1/segment?title=My%20segment
Example response: {"status":"OK","created":true,"segment_id":12345}
Segment Population
After the segment ID has been received, Mapp uploads users to the segment using one of the following approaches.
- No batch: Send one API call per user. Example request: curl -XPOST https://api.third-party.com/v1/segment?id=12345&userid=abcdef123. Typically these calls have no response but only a 200 OK status.
- Micro batch: Send one API call per batch of users, typically between 10 and 1000 users per batch. Example request: curl -XPOST --data '[{"segment":12345,"userid":"abcdef123"},{"segment":45678,"userid":"ghjkl1321"}]' https://api.third-party.com/v1/segment. Typically these calls have no response but only a 200 OK status. Sometimes the amount of successful mutations is returned.
- Semi real-time: Every few minutes we send one file with a list of user IDs which have to be appended to the existing segment (deprecated). We can format the file in a lot of different ways, but typical is a one column TSV with new lines and a single user ID on each line. The filename we recommend is the following format: Mapp_dmp_<segmentId:integer>_<year:integer>_<month:integer>_<day:integer>_<hour:integer>_<minute:integer>.tsv.gz. As we process and compute all data in real-time we deliver files very regularly with changes. The files we upload are not the full lists of users that belong to the audience, but only the additions. Typically we can work with expiring audience membership (time-to-live, TTL) or we can support removal of audience members with DELETE API calls or add an operation type to the file (e.g. add or remove).
Recommendations
- Don't have manual steps in the process as described above; it should be fully automated so that a client can immediately start targeting the audience(s).
- Usage of the micro batching via API is industry standard as it's fast, scalable and efficient.
- File upload is unreliable and prone to errors; we deprecate the usage of this and can only implement this as an exception.