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 ParameterDescription
PIXEL_IDEvents 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.

NOTE: Your Pixel must be at least 24 hours old in order for it to be accepted by the authentication flow.
ACCESS_TOKENGenerate this in Events Manager.

Adding a Snapchat CAPI Sync

To gather the ScCid value (Snapchat click ID), 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
  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 KeyDescriptionExpected 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.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.emType: string.
The hashed email address of the user
N/A - Expression
user_data.phType: string.
The hashed phone number of the user
N/A - Expression
user_data.fnType: string.
The hashed first name of the user
N/A - Expression
user_data.lnType: string.
The hashed last name of the user
N/A - Expression
user_data.geType: string.
The hashed gender of the user
N/A - Expression
user_data.ctType: string.
The hashed city of the user
N/A - Expression
user_data.stType: string.
The hashed state of the user
N/A - Expression
user_data.zpType: string.
The hashed zip code of the user
N/A - Expression
user_data.countryType: 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 the metarouter value.
Enrichment - metarouter

Event Specific

Identify

Output KeyDescriptionExpected Input
event_name
Required
Type: string.
The name of the event.
Enrichment - LOGIN

Page

Output KeyDescriptionExpected Input
event_name
Required
Type: string.
The name of the event
Enrichment - PAGE_VIEW
custom_data.content_nameType: string.
The name of the content
N/A - Expression

Products Searched

Output KeyDescriptionExpected Input
event_name
Required
Type: string.
The name of the event
Enrichment - SEARCH
custom_data.search_stringType: string.
The search string used
properties.query

Product List Viewed

Output KeyDescriptionExpected Input
event_name
Required
Type: string.
The name of the event
Enrichment - LIST_VIEW
custom_data.content_categoryType: string.
The category of the content
properties.category
custom_data.content_idsType: array.
An array of content IDs
N/A - Expression
custom_data.content_typeType: string.
The type of content
Enrichment - product

Product Viewed

Output KeyDescriptionExpected Input
event_name
Required
Type: string. The name of the eventEnrichment - VIEW_CONTENT
custom_data.content_nameType: string. The name of the contentproperties.name
custom_data.content_categoryType: string. The category of the contentproperties.category
custom_data.content_idsType: string. The ID of the contentproperties.product_id
custom_data.content_typeType: string. The type of contentEnrichment - product

Product Added

Output KeyDescriptionExpected Input
event_name
Required
Type: string. The name of the eventEnrichment - ADD_CART
`custom_data.content_name`Type: string. The name of the contentproperties.name
custom_data.content_categoryType: string. The category of the contentproperties.category
custom_data.content_idsType: string. The ID of the contentproperties.product_id
custom_data.contentsType: array. An array of content detailsN/A - Expression
custom_data.currencyType: string. The currency of the transactionN/A - Expression
custom_data.num_itemsType: number. The number of itemsN/A - Expression
custom_data.valueType: number. The value of the transactionN/A - Expression
custom_data.content_typeType: string. The type of contentEnrichment - product

Product Added to Wishlist

Output KeyDescriptionExpected Input
event_name
Required
Type: string. The name of the eventEnrichment - ADD_TO_WISHLIST
custom_data.content_nameType: string. The name of the contentproperties.name
custom_data.content_categoryType: string. The category of the contentproperties.category
custom_data.content_idsType: string. The ID of the contentproperties.product_id
custom_data.contentsType: array. An array of content detailsN/A - Expression
custom_data.currencyType: string. The currency of the transactionN/A - Expression
custom_data.num_itemsType: number. The number of itemsN/A - Expression
custom_data.valueType: number. The value of the transactionN/A - Expression
custom_data.content_typeType: string. The type of contentEnrichment - product

Cart Viewed

Output KeyDescriptionExpected Input
event_name
Required
Type: string. The name of the eventEnrichment - VIEW_CONTENT
custom_data.content_nameType: string. The name of the contentN/A - Expression
custom_data.content_idsType: array. An array of content IDsN/A - Expression
custom_data.contentsType: array. An array of content detailsN/A - Expression
custom_data.currencyType: string. The currency of the transactionN/A - Expression
custom_data.num_itemsType: number. The number of itemsN/A - Expression
custom_data.valueType: number. The value of the transactionN/A - Expression
custom_data.content_typeType: string. The type of contentEnrichment - product

Checkout Started

Output KeyDescriptionExpected Input
event_name
Required
Type: string. The name of the eventEnrichment - START_CHECKOUT
custom_data.content_nameType: string. The name of the contentN/A - Expression
custom_data.content_idsType: array. An array of content IDsN/A - Expression
custom_data.contentsType: array. An array of content detailsN/A - Expression
custom_data.currencyType: string. The currency of the transactionN/A - Expression
custom_data.num_itemsType: number. The number of itemsN/A - Expression
custom_data.valueType: number. The value of the transactionN/A - Expression
custom_data.content_typeType: string. The type of contentEnrichment - product

Payment Info Entered

Output KeyDescriptionExpected Input
event_name
Required
Type: string. The name of the eventEnrichment - ADD_BILLING
custom_data.content_nameType: string. The name of the contentproperties.order_id

Order Completed

Output KeyDescriptionExpected Input
event_name
Required
Type: string. The name of the eventEnrichment - PURCHASE
custom_data.content_nameType: string. The name of the contentN/A - Expression
custom_data.content_idsType: array. An array of content IDsN/A - Expression
custom_data.contentsType: array. An array of content detailsN/A - Expression
custom_data.currency
Required
Type: string. The currency of the transactionN/A - Expression
custom_data.num_itemsType: number. The number of itemsN/A - Expression
custom_data.order_idType: string. The order IDproperties.order_id
custom_data.value
Required
Type: number. The value of the transactionN/A - Expression
custom_data.content_typeType: string. The type of contentEnrichment - product

Promotion Viewed

Output KeyDescriptionExpected Input
event_name
Required
Type: string. The name of the eventEnrichment - AD_VIEW
custom_data.content_nameType: string. The name of the contentproperties.name

Promotion Clicked

Output KeyDescriptionExpected Input
event_name
Required
Type: string. The name of the eventEnrichment - AD_CLICK
custom_data.content_nameType: string. The name of the contentproperties.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.

AttributeExampleSync Injector Required?
user_data.em
Required**
SHA-256 hash: 587dfd511a0c05a6d71c4afae60bece0a5f8ccf2f7e7b1c74e3b9f1a5f8f5152No
user_data.ph
Required**
SHA-256 hash: b1a8fd06fc2a2d5f2f03027e6d0d85ad9a9c0d1dcb8821b4d4cfc4d6d38b8b82No
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