Snapchat CAPI

What Is Snapchat CAPI?

Snapchat Ads is a platform provided by Snapchat for businesses to create and manage advertising campaigns that reach Snapchat's vast user base. With Snapchat Ads, advertisers can create engaging ads in various formats, including Snap Ads, Story Ads, and Filters, to reach their target audience. The platform offers advanced targeting options based on demographics, interests, behaviors, and location, allowing advertisers to tailor their campaigns for maximum effectiveness. Additionally, Snapchat provides analytics tools to measure the performance of ads and optimize campaigns for better results.

Snapchat CAPI (Conversion API) is a server-to-server integration that allows advertisers to track conversions and send event data directly to Snapchat's servers. It enables advertisers to measure the effectiveness of their ad campaigns more accurately by bypassing browser-based tracking methods like pixels.

What are the benefits of integrating MetaRouter with Snapchat CAPI?

  • Enhanced Data Accuracy: MetaRouter allows for real-time, server-side data collection, which improves the accuracy and reliability of the data sent to Snapchat CAPI by reducing discrepancies caused by browser limitations or ad blockers.
  • Reduced Site Latency: By handling data server-side, MetaRouter minimizes the impact on website performance, leading to faster page load times and a better user experience.
  • Enables Removal of Snapchat Tag: Integration with Snapchat CAPI through MetaRouter eliminates the need for client-side Snapchat tags, simplifying tag management and reducing the risk of tag-related issues.
  • Optimized Ad Performance: Accurate and complete data sent through Snapchat CAPI allows for better ad targeting and measurement, leading to improved campaign performance and ROI.

Snapchat Ads vs Snapchat CAPI

  • Snapchat Ads Integration
    • Uses IP, user agent, and anonymous ID as main identifiers.
    • Does not require authentication.
  • Snapchat CAPI Integration
    • Uses IP, user agent, anonymous ID, PII such as email and/or phone, and also supports click ID which may help with anonymous user identification.
    • Requires a sync injector to gather and persist the click ID.
    • Authentication is required.

Getting Started - From Your Snapchat Account

Set up CAPI and generate a new access token: Please use these instructions to generate a CAPI token.

Grab your Pixel ID:

  1. Go to Business Dashboard.
  2. Click on “Pixels” on the left navigation.
  3. Your Pixel ID will be listed under the pixel name.
    1. NOTE: Your Pixel must be at least 24 hours old in order for it to be accepted by the authentication flow.

How to check events:

  1. Once you've implemented the Snapchat - CAPI integration from MetaRouter, you can check your events by going to your Snapchat Ads dashboard.
  2. Go to Event Manager from the upper-navigation.
  3. You should see a events populating in the event source you set up for the integration. You can click into the widget to see details on events that are populating.

Getting Started - From Your MetaRouter Account

Adding a Snapchat CAPI integration.

From the integration library, add a Snapchat CAPI integration. Then, fill out the Connection Parameters:

Connection Parameter

Description

PIXEL_ID

Events taking place on a web property. If you are passing the same events via a Pixel on your website, you should use the pixel_id to ensure all events are entering the same pipeline for deduplication.

This field is optional. Omit this field if you do not want the sync injector to use the_scid.

  • *NOTE:** Your Pixel must be at least 24 hours old in order for it to be accepted by the authentication flow.

ACCESS_TOKEN

Generate this in Events Manager.


Adding a Snapchat CAPI Sync

To gather the ScCid value (Snapchat click ID) and the _scid value (Snapchat cookie), you must add a Snapchat CAPI sync.

  1. From the Pipelines page, find the pipeline associated with the web property you’d like to add a sync to. Hover over the three dot dropdown and select “Build AJS File.”
  2. In the Identity Syncs section, select the Snapchat CAPI sync.
  3. Fill out the following fields:
    1. Consent Type - We recommend that you consult with your legal team when determining your consent requirements.
    2. Cookie Lifetime (in days) - default 37 days
    3. Pixel ID - Please use the same Pixel ID as with your connection parameters in the starter kit. Please see above for information regarding grabbing your Pixel ID.
  4. Scroll down and click the Save and Build File button.
  5. Deploy your AJS file to propagate changes to your web property.

Event Mappings

MetaRouter provides all of the event mappings that Snapchat CAPI integrations typically require. You may add custom events, parameters or mappings in accordance with Snapchat’s API documentation.

Global

Global mappings will be applied to all events. If your parameter names do not match the Expected Inputs provided, you will need to overwrite the Inputs provided with your own.

Output Key

Description

Expected Input

event_id Required

Type: string.
A unique identifier for the event

messageId

event_time
Required

Type: string.
The time of the event in UNIX milliseconds

N/A - Expression

event_source_url
Required

Type: string.
The URL where the event took place

context.page.url

action_source
Required

Type: string.
The source of the action

N/A - Expression

user_data.external_id
Required

Type: string.
An identifier for the user

anonymousId

user_data.sc_click_id
Highly Recommended

Type: string.
The Snapchat click ID

context.providers.snapchatCAPI.ScCid

user_data.sc_cookie1
Recommended

Type: string.
The Snapchat cookie ID.

context.providers.snapchatCAPI._scid

user_data.client_ip_address
Required

Type: string.
The IP address of the client

context.ip

user_data.client_user_agent
Required

Type: string.
The user agent of the client

context.userAgent

user_data.em

Type: string.
The hashed email address of the user

N/A - Expression

user_data.ph

Type: string.
The hashed phone number of the user

N/A - Expression

user_data.fn

Type: string.
The hashed first name of the user

N/A - Expression

user_data.ln

Type: string.
The hashed last name of the user

N/A - Expression

user_data.ge

Type: string.
The hashed gender of the user

N/A - Expression

user_data.ct

Type: string.
The hashed city of the user

N/A - Expression

user_data.st

Type: string.
The hashed state of the user

N/A - Expression

user_data.zp

Type: string.
The hashed zip code of the user

N/A - Expression

user_data.country

Type: string.
The hashed country of the user

N/A - Expression

integration
Required

Type: string.
A static value for integration type. By Snapchat's request, please do not change themetarouter value.

Enrichment - metarouter


Event Specific

Identify

Output Key

Description

Expected Input

event_name Required

Type: string.
The name of the event.

Enrichment - LOGIN

Page

Output Key

Description

Expected Input

event_name Required

Type: string.
The name of the event

Enrichment - PAGE_VIEW

custom_data.content_name

Type: string.
The name of the content

N/A - Expression

Products Searched

Output Key

Description

Expected Input

event_name Required

Type: string.
The name of the event

Enrichment - SEARCH

custom_data.search_string

Type: string.
The search string used

properties.query

Product List Viewed

Output Key

Description

Expected Input

event_name Required

Type: string.
The name of the event

Enrichment - LIST_VIEW

custom_data.content_category

Type: string.
The category of the content

properties.category

custom_data.content_ids

Type: array.
An array of content IDs

N/A - Expression

custom_data.content_type

Type: string.
The type of content

Enrichment - product

Product Viewed

Output Key

Description

Expected Input

event_name Required

Type: string. The name of the event

Enrichment - VIEW_CONTENT

custom_data.content_name

Type: string. The name of the content

properties.name

custom_data.content_category

Type: string. The category of the content

properties.category

custom_data.content_ids

Type: string. The ID of the content

properties.product_id

custom_data.content_type

Type: string. The type of content

Enrichment - product

Product Added

Output Key

Description

Expected Input

event_name Required

Type: string. The name of the event

Enrichment - ADD_CART

`custom_data.content_name

`Type: string. The name of the content

properties.name

custom_data.content_category

Type: string. The category of the content

properties.category

custom_data.content_ids

Type: string. The ID of the content

properties.product_id

custom_data.contents

Type: array. An array of content details

N/A - Expression

custom_data.currency

Type: string. The currency of the transaction

N/A - Expression

custom_data.num_items

Type: number. The number of items

N/A - Expression

custom_data.value

Type: number. The value of the transaction

N/A - Expression

custom_data.content_type

Type: string. The type of content

Enrichment - product

Product Added to Wishlist

Output Key

Description

Expected Input

event_name Required

Type: string. The name of the event

Enrichment - ADD_TO_WISHLIST

custom_data.content_name

Type: string. The name of the content

properties.name

custom_data.content_category

Type: string. The category of the content

properties.category

custom_data.content_ids

Type: string. The ID of the content

properties.product_id

custom_data.contents

Type: array. An array of content details

N/A - Expression

custom_data.currency

Type: string. The currency of the transaction

N/A - Expression

custom_data.num_items

Type: number. The number of items

N/A - Expression

custom_data.value

Type: number. The value of the transaction

N/A - Expression

custom_data.content_type

Type: string. The type of content

Enrichment - product

Cart Viewed

Output Key

Description

Expected Input

event_name Required

Type: string. The name of the event

Enrichment - VIEW_CONTENT

custom_data.content_name

Type: string. The name of the content

N/A - Expression

custom_data.content_ids

Type: array. An array of content IDs

N/A - Expression

custom_data.contents

Type: array. An array of content details

N/A - Expression

custom_data.currency

Type: string. The currency of the transaction

N/A - Expression

custom_data.num_items

Type: number. The number of items

N/A - Expression

custom_data.value

Type: number. The value of the transaction

N/A - Expression

custom_data.content_type

Type: string. The type of content

Enrichment - product

Checkout Started

Output Key

Description

Expected Input

event_name Required

Type: string. The name of the event

Enrichment - START_CHECKOUT

custom_data.content_name

Type: string. The name of the content

N/A - Expression

custom_data.content_ids

Type: array. An array of content IDs

N/A - Expression

custom_data.contents

Type: array. An array of content details

N/A - Expression

custom_data.currency

Type: string. The currency of the transaction

N/A - Expression

custom_data.num_items

Type: number. The number of items

N/A - Expression

custom_data.value

Type: number. The value of the transaction

N/A - Expression

custom_data.content_type

Type: string. The type of content

Enrichment - product

Payment Info Entered

Output Key

Description

Expected Input

event_name Required

Type: string. The name of the event

Enrichment - ADD_BILLING

custom_data.content_name

Type: string. The name of the content

properties.order_id

Order Completed

Output Key

Description

Expected Input

event_name Required

Type: string. The name of the event

Enrichment - PURCHASE

custom_data.content_name

Type: string. The name of the content

N/A - Expression

custom_data.content_ids

Type: array. An array of content IDs

N/A - Expression

custom_data.contents

Type: array. An array of content details

N/A - Expression

custom_data.currency
Required

Type: string. The currency of the transaction

N/A - Expression

custom_data.num_items

Type: number. The number of items

N/A - Expression

custom_data.order_id

Type: string. The order ID

properties.order_id

custom_data.value
Required

Type: number. The value of the transaction

N/A - Expression

custom_data.content_type

Type: string. The type of content

Enrichment - product

Promotion Viewed

Output Key

Description

Expected Input

event_name Required

Type: string. The name of the event

Enrichment - AD_VIEW

custom_data.content_name

Type: string. The name of the content

properties.name

Promotion Clicked

Output Key

Description

Expected Input

event_name Required

Type: string. The name of the event

Enrichment - AD_CLICK

custom_data.content_name

Type: string. The name of the content

properties.name


Required Identifiers

Identifiers must be mapped to Snapchat CAPI in order for successful user matching to occur. Without the required IDs, any events sent to Snapchat CAPI may not be reflected accurately in reporting. For your convenience, required and recommended IDs are mapped as Global parameters to ensure they are added to every event.

**At least one of the following “Required” identifiers to match your events to users.

Attribute

Example

Sync Injector Required?

user_data.em Required**

SHA-256 hash: 587dfd511a0c05a6d71c4afae60bece0a5f8ccf2f7e7b1c74e3b9f1a5f8f5152

No

user_data.ph
Required**

SHA-256 hash: b1a8fd06fc2a2d5f2f03027e6d0d85ad9a9c0d1dcb8821b4d4cfc4d6d38b8b82

No

user_data.client_ip_address
Required** If using IP, user agent must also be used.

"192.168.0.1”

No

user_data.client_user_agent
Required** If using user agent, IP must also be used.

"Mozilla/5.0 (Windows NT 10.0; Win64; x64)"

No

user_data.sc_click_id
Highly Recommended

“7b3a7917-a82a-47e8-9728-e1b3b045abb2”

Yes


Additional Snapchat CAPI Documentation

Snapchat CAPI overview
Auth
CAPI Checklist
Sending ClickID
CAPI Best Practices
User Data Parameters