Snapchat Conversions API Export Integration

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

Overview

The Snapchat Conversions API (CAPI) connector enables server-side tracking and measuring conversion events across web, mobile, and offline channels. By integrating directly with Snapchat's Events Manager, this connector helps businesses measure campaign performance and optimize ad delivery more effectively across Snapchat's 300M+ daily active users.

Key capabilities:

• Web Events: Server-side tracking to complement pixel data for enhanced measurement accuracy
• Mobile App Events: Direct integration of in-app conversion events
• Offline Events: Support for non-digital conversions like in-store purchases
• Data Validation: Automated event validation and formatting to Snapchat's CAPI specifications

This server-side integration provides more reliable conversion tracking and improved advertising performance measurement compared to client-side solutions alone.

Prerequisites

• Basic knowledge of Treasure Data, including the TD Toolbelt.
• Basic knowledge of Snapchat Business.
• Snapchat Access Token or Snapchat Business account

Limitations & Known Issues

• Event Time Restrictions

  • Events older than 7 days (based on event_time) will be skipped during processing
  • Event time validations use UTC timezone for epoch conversions and 7-day window calculations

• Invalid Event Source ID Error Message Discrepancies between oAuth Authentication and Conversion API token authentication

  • Different authentication methods produce varying error responses for invalid event_source_id:
    • When using Conversion API Token Authentication, the error message will be:
      {  "status": "INVALID",  "reason": "Unauthorized resources" }

• When using OAuth Authentication, the error message will be:

  {  "status": "INVALID",  "test_event": true,  "reason": "At least one of the events is invalid.",  "event_logs": [    {   "event": 1,     "status": "INVALID",     "errors": {       "codes": [         "523"       ],       "error_msgs": [         "The provided asset id must be valid UUID format."       ]            }  }}

• When using OAuth authentication, the error response message does not explicitly indicate an invalid Event Source ID, instead referring to an invalid “asset id.” Therefore, for more reliable error handling when you’re unsure about the Event Source ID, it's recommended to use Conversion API Token authentication when running the job.

• Anonymous ID Field (anon_id): Despite being documented as a standard field in the “User Data Parameter” section of the API documentation (Link), anon_id cannot be included in the user_data object

  • Attempting to use anon_id in user_data results in the following error:

    {  "status": "INVALID",  "reason": "Request parsing failed. Ensure the request body is correctly formatted." }

  • So, as a workaround, we have to map anon_id to the custom data object instead of the user_data object to avoid the API error.

Create a New Connection via TD Console

Before running your query, you must create and configure the data connection on the TD Console. As part of the data connection, you provide authentication to access the integration. Complete the following steps.

1. Open TD Console.

2. Navigate to Integrations Hub > Catalog.

3. Search for and select Snapchat Conversions API. Hover over the icon and selectCreate Authentication.

4. Ensure that the Credentials tab is selected, and then enter credential information for the integration. Choose one of the following

   1. **OAuth Authentication Workflow:**Select the link "Click here" to start the OAuth authentication flow. After completing the authentication, a new OAuth connection will be created and available in the dropdown.

      

      Select Continue to create a new connection.

      b. Conversion API Token Workflow: Obtain the access token from the Snapchat Business Manager and input it in the Conversion API Token field.

      

      Authentication Fields

      Parameter	Description
      Authentication Mode	Authentication method. Supported values: - oAuth Connection: OAuth Authentication - Conversions API Token: Long live access token generated in the Snapchat Business Manager.
      Conversions API Token	You can obtain the Conversions API Token from the Snapchat Business Manager. This parameter is only available for Conversion API Token authentication methods.

5. Select Continue.

6. Enter a name for your authentication, and select Done.

Configure a Query Result for Export

The TD Console supports multiple ways to export data. Please follow these steps to export data from the Data Workbench.

1. Navigate to Data Workbench > Queries.
2. Select New Query, and define your query.
3. Select Export Results to configure the data exporting.
4. Select an existing Snapchat CAPI authentication or create a new one described previously
5. Select Done.

Connector Configuration Parameters

Detailed Guide for Query Result Data Specs

To upload event data to Snapchat CAPI, you need to build a data export query that includes a combination of standard fields and custom fields that adhere to Snapchat CAPI guidelines. For standard fields, ensure the column names match those listed in the "Field/Column-Level Specifications" section. The connector automatically normalizes the column names to match Snapchat CAPI's required format, so you do not need to worry about case sensitivity. For example, for the default field "event_name," the column name in your export query can be written in any case, such as "EVENT_NAME," "event_name," or "Event_Id." The connector will standardize the column name to "event_name" to meet Snapchat CAPI's requirements.

To successfully upload/modify user profile data to Snapchat CAPI, you must construct an export query that adheres to specific data specifications. These specifications are divided into two levels:

• Export Query Specifications (or Dataset-level data specs): This section describes the requirements and rules that apply to your entire query result dataset, such as the presence of required fields and data validation rules that span multiple fields.
• Field/Column-Level Specifications: This section details the requirements and rules for individual fields/columns in your dataset, such as data types and formats for each field.

Export Query Specifications

[
  {
    "id": "ABC123",
    "quantity": 2,
    "item_price": 29.99,
    "delivery_category": "standard"
  },
  {
    "id": "XYZ789",
    "quantity": 1,
    "item_price": 49.99,
    "delivery_category": "express"
  }
]

Field/Column-Level Specifications

There is Special Field Handling

Country Field

• For user_data object: Use column name “country” (case-insensitive)
• For custom_data object: Use column name “custom_country” (case-insensitive)

Punctuation Marks Removal

Specific fields require the removal of punctuation marks. When this applies, the following characters will be removed:

• Basic punctuation: . , ! ? ; : - — " ' ( ) [ ] { } / _
• Special characters: & * + = @ # $ % ^ ~ |

Handling Date-Time

The integration can handle values cast as timestamps or in ISO-8601 date-time string format for date-time custom field columns. When using ISO-8601 date-time strings, ensure the value includes the letter “Z” at the end to allow the connector to detect and convert the date-time value into a Unix time value as required by Snapchat CAPI’s API contract.

Examples for Handling Date-Time Custom Field Columns

1. Casting as Timestamp

• Create a column of type string in the source data table:

  ALTER TABLE source_data_table ADD COLUMN date_time_field VARCHAR;

• Insert date-time value strings into that column:

  INSERT INTO source_data_table (id, date_time_field)VALUES(1, '2024-08-28'),(2, '2024-08-28 15:30:00'),(3, '2024-08-28T15:30:00');

• Cast the column value as timestamp:

  SELECT id, CAST(date_time_field AS timestamp) AS date_time_field FROM source_data_table;

2. Using ISO-8601 Date-Time String

• Create a column of type string in the source data table:

  ALTER TABLE source_data_table ADD COLUMN date_time_field VARCHAR;

• Insert date-time value strings into that column, ensuring they are formatted as ISO-8601 with a “T” separator and “Z” at the end:

  INSERT INTO source_data_table (id, date_time_field)VALUES(1, '2024-08-28T00:00:00Z'),(2, '2024-05-28T15:30:00.123Z'),(3, '2024-02-28T15:30:00Z');

• Use the column directly in the query:

  SELECT id, date_time_field FROM source_data_table;

Standard Fields for Server Parameters (Top-level parameters)

Standard Fields for User Data Object

The following fields are used to identify users and their attributes. At least one identifier field is required from: email (em), phone (ph), sc_click_id, client_ip_address, client_user_agent, or mobile advertiser id (madid).

*At least one of these identifier fields is required.

Optional User Attributes

Additional Identifier Fields

Important Notes about User Data:

1. Conditional Requirements: You must include at least one of the conditional identifier fields (em, ph, sc_click_id, client_ip_address, client_user_agent, or madid).
2. Automatic Processing: The connector automatically handles:
   • Field normalization (lowercase conversion, space removal, etc.)
   • Hashing of sensitive fields
   • UTF-8 encoding where required
3. Multiple Values: Fields marked as String/Array can accept either a single value or multiple values

Standard Fields for Custom Data Object

E-Commerce Related Fields

Travel-Related Fields

Location-Related Fields

Travel Schedule Fields

Accommodation-Related Fields

Standard Fields for App Data Object

extinfo Array Specifications

The extinfo array must contain exactly 16 elements in the following order,  use the exact column name as specified in the "Column Name" for the connector to build the accurate array:

Example complete extinfo array:

["i2", "com.snapchat.sdk", "1.0", "1.0", "10.3.1", "iphone14", "En_US", "EDT", "AT&T", "320", "568", "2", "2", "15", "8", "USA/New York"]

Important Notes for App Events:

1. All three fields (advertiser_tracking_enabled, app_id, and extinfo) are required for app events
2. The extinfo array must maintain the exact order specified above
3. Integer values in extinfo must be provided as Int64 type
4. First element of extinfo determines the platform (iOS/Android)

(Optional) Schedule Query Export Jobs

You can use Scheduled Jobs with Result Export to periodically write the output result to a target destination that you specify.

Treasure Data's scheduler feature supports periodic query execution to achieve high availability.

When two specifications provide conflicting schedule specifications, the specification requesting to execute more often is followed while the other schedule specification is ignored.

For example, if the cron schedule is '0 0 1 * 1', then the 'day of month' specification and 'day of week' are discordant because the former specification requires it to run every first day of each month at midnight (00:00), while the latter specification requires it to run every Monday at midnight (00:00). The latter specification is followed.

Scheduling your Job Using TD Console

1. Navigate to Data Workbench > Queries

2. Create a new query or select an existing query.

3. Next to Schedule, select None.

4. In the drop-down, select one of the following schedule options:

   Drop-down Value	Description
   Custom cron...	Review Custom cron... details.
   @daily (midnight)	Run once a day at midnight (00:00 am) in the specified time zone.
   @hourly (:00)	Run every hour at 00 minutes.
   None	No schedule.

Custom cron... Details

 *    *    *    *    *
 -    -    -    -    -
 |    |    |    |    |
 |    |    |    |    +----- day of week (0 - 6) (Sunday=0)
 |    |    |    +---------- month (1 - 12)
 |    |    +--------------- day of month (1 - 31)
 |    +-------------------- hour (0 - 23)
 +------------------------- min (0 - 59)

The following named entries can be used:

• Day of Week: sun, mon, tue, wed, thu, fri, sat.
• Month: jan, feb, mar, apr, may, jun, jul, aug, sep, oct, nov, dec.

A single space is required between each field. The values for each field can be composed of:

1. (Optional) You can delay the start time of a query by enabling the Delay execution.

Execute the Query

Save the query with a name and run, or just run the query. Upon successful completion of the query, the query result is automatically exported to the specified destination.

(Optional) You can delay the start time of a query by enabling the Delay execution.

Activate a Segment in Audience Studio

You can also send segment data to the target platform by creating an activation in the Audience Studio.

1. Navigate to Audience Studio.
2. Select a parent segment.
3. Open the target segment, right-mouse click, and then select Create Activation.
4. In the Details panel, enter an Activation name and configure the activation according to the previous section on Configuration Parameters.
5. Customize the activation output in the Output Mapping panel.

• Attribute Columns
  • Select Export All Columns to export all columns without making any changes.
  • Select + Add Columns to add specific columns for the export. The Output Column Name pre-populates with the same Source column name. You can update the Output Column Name. Continue to select + Add Columnsto add new columns for your activation output.
• String Builder
  • + Add string to create strings for export. Select from the following values:
    • String: Choose any value; use text to create a custom value.
    • Timestamp: The date and time of the export.
    • Segment Id: The segment ID number.
    • Segment Name: The segment name.
    • Audience Id: The parent segment number.

6. Set a Schedule.

• Select the values to define your schedule and optionally include email notifications.

7. Select Create.

(Optional) Export Integration Using the CLI

You can also use CLI (Toolbelt) to export results to Snapchat Conversion CAPI.

You need to specify the information for export to your Snapchat server using the *--result option of*the td query command. For more information about the *td query*command, refer to this article.

The format of the option is JSON, and the general structure is as follows.

{
  "type": "snapchat_conversion",
  "auth_method": "oauth",
  "oauth_credentials_id": "xxxxxxxxxxx",
  "event_source_type": "web",
  "event_source_id": "xxxxxxxxxxx",
  "send_test_events": false,
  "skip_invalid_records": true
}

{
  "type": "snapchat_conversion",
  "auth_method": "api_token",
  "api_token": "xxxxxxxxxxx",
  "event_source_type": "web",
  "event_source_id": "xxxxxxxxxxx",
  "send_test_events": false,
  "skip_invalid_records": true
}

Parameters

Example for Usage

OAuth authentication

$ td query --result '{"type":"snapchat_conversion","auth_method":"oauth","oauth_credentials_id":"xxx","event_source_type":"WEB","event_source_id":"xxx", "send_test_events":false,"skip_invalid_records":true}' -d sample_datasets "select ........ from ........" -T presto

API Token authentication

$ td query --result '{"type":"snapchat_conversion","auth_method":"api_token","api_token":"xxx","event_source_type":"WEB","event_source_id":"xxx", "send_test_events":false,"skip_invalid_records":true}' -d sample_datasets "select ........ from ........" -T presto

Related articles

Other Configurations

• The Result Export can be scheduled to periodically upload data to a target destination.
• All import and export integrations can be added to a TD Workflow. The td data operator can export a query result to a specified integration. For more information, see Reference for Treasure Data Operators.