# Snapchat Conversion Cloud Mode Integration

After you have [successfully instrumented]({{< ref "destinations/streaming-destinations/snapchat-conversion/setup-guide.md" >}}) Snapchat Conversion as a destination in RudderStack, follow this guide to correctly send your events to Snapchat in [cloud mode]({{< ref "/destinations/rudderstack-connection-modes.md#cloud-mode" >}}) by leveraging their [Conversions API](https://businesshelp.snapchat.com/s/article/conversions-api?language=en_US).

{{< warning >}}
You must generate the events at least 28 days before for them to be eligible for reporting via the Conversions API.
{{< /warning >}}

Find the open source transformer code for this destination in the [GitHub repository](https://github.com/rudderlabs/rudder-transformer/tree/main/src/v0/destinations/snapchat_conversion).

## Track

You can use the [`track`]({{< ref "event-spec/standard-events/track.md" >}}) event to capture user actions along with their associated properties and send this information to Snapchat.

Note that:

- RudderStack tracks and sends the web, mobile, and offline events to Snapchat via their v3 endpoint (`https://tr.snapchat.com/v3/{ID}/events`), where `{ID}` is the Advertiser ID associated with your Snapchat business account.
- It uses Bearer authentication leveraging the Snap API token for authenticating all requests. OAuth is not supported currently.

A sample `track` call is shown below:

```javascript
rudderanalytics.track("Order Completed", {
  order_id: "1234",
  currency: "USD",
  products: [{
      product_id: "345676543",
      price: 7.99
    },
  ],
}, {
  context: {
    traits: {
      email: "alex@example.com",
      phone: "+1-202-555-0146"

    }
  }
})
```

RudderStack recommends passing at least one of the following fields to send a `track` event to Snapchat successfully:

- `email`
- `phone`
- `idfa`
- `ip` and `userAgent`

You can also send the `eventConversionType` property in your `track` events to determine the type of event to send to Snapchat (web, mobile, or offline).

| Snapchat event type | `eventConversionType` property value |
| :-----|:----|
| `WEB` | `web` |
| `MOBILE_APP` | `mobile` / `mobile_app` |
| `OFFLINE` | `offline` | 

{{< warning >}}
Make sure to specify the exact property values.
{{< /warning >}}

If `eventConversionType` is not found in the event, RudderStack checks if `channel` is present. If `channel` is absent too, RudderStack automatically sets `eventConversionType` to `OFFLINE`.

An example highlighting the use of `eventConversionType` is shown:

```javascript
rudderanalytics.track("Products Searched", {
query: "HDMI cable",
eventConversionType: "mobile"
});
```

### Event mappings

{{< warning >}}
This destination does not strictly adhere to the [RudderStack Ecommerce Event Spec]({{< ref "event-spec/ecommerce-events-spec/" >}}).
{{< /warning >}}

RudderStack automatically maps the following ecommerce events to the corresponding Snapchat Conversion events:

| RudderStack event | Snapchat Conversion event |
|:--------------------------------|:--------------------------|
| Products Searched | `SEARCH` |
| Product List Viewed | `VIEW_CONTENT` |
| Promotion Viewed | `AD_VIEW` |
| Promotion Clicked | `AD_CLICK` |
| Product Viewed | `VIEW_CONTENT` |
| Product Added | `ADD_CART` |
| Checkout Started | `START_CHECKOUT` |
| Payment Info Entered | `ADD_BILLING` |
| Order Completed | `PURCHASE` |
| Product Added to Wishlist | `ADD_TO_WISHLIST` |

RudderStack **does not automatically map** the following events and passes their properties as is, without any modification:

- `ACHIEVEMENT_UNLOCKED`
- `APP_INSTALL`
- `APP_OPEN`
- `COMPLETE_TUTORIAL`
- `INVITE`
- `LIST_VIEW`
- `LEVEL_COMPLETE`
- `LOGIN`
- `PAGE_VIEW`
- `RATE`
- `RESERVE`
- `SAVE`
- `SIGN_UP`
- `SHARE`
- `SPENT_CREDITS`
- `START_TRIAL`
- `SUBSCRIBE`

### Property mappings

{{< tabs tabTotal="2" >}}
{{% tab tabName="API v3" %}}

| RudderStack property | Snapchat Conversion property |
| :--- | :---- |
| `properties.brands` <br /> <span style="color: #4D4DFF;font-size:12px;">Array</span> | `custom_data.brands` |
| `properties.click_id` | `user_data.sc_click_id` |
| `properties.uuid_c1` | `user_data.sc_cookie1` |
| `properties.att_status` | `app_data.advertiser_tracking_enabled` |
| `properties.idfv`<br />`context.device.id` | `user_data.idfv` |
| `properties.adId`<br />`context.device.advertisingId` | `user_data.madid` |
| `properties.item_ids` | `custom_data.content_ids` |
| `properties.category` | `custom_data.content_category` |
| `properties.number_items`<br />`properties.quantity` | `custom_data.num_items` |
| `properties.price`<br />`properties.value`<br />`properties.revenue`<br />(`properties.products.price` * `properties.products.quantity`) | `custom_data.value` |
| `properties.currency` | `custom_data.currency` |
| `properties.search_string` | `custom_data.search_string` |
| `properties.client_dedup_id`<br />`properties.transaction_id`<br />`properties.transactionId` | `event_id` |
| `properties.eventConversionType` | `action_source` |
| `properties.products.$.product_id` <br /> `properties.products.$.sku` <br /> `properties.products.$.id` | `custom_data.contents.$.id` |
| `properties.products.$.price` | `custom_data.contents.$.Item_price` |
| `properties.products.$.quantity` | `custom_data.contents.$.quantity` |
| `properties.products.$.delivery_category`  | `custom_data.contents.$.delivery_category` |
| `properties.products.$.brand` | `custom_data.contents.$.brand` |
| `properties.$.product_id` <br /> `properties.$.sku` <br /> `properties.$.id` | `custom_data.contents.$.id` |
| `properties.$.price` | `custom_data.contents.$.Item_price` |
| `properties.$.quantity` | `custom_data.contents.$.quantity` |
| `properties.$.delivery_category` | `custom_data.contents.$.delivery_category` |
| `context.ip`<br />`request_ip` | `user_data.client_ip_address` |
| `context.userAgent` | `user_data.client_user_agent` |
| `context.page.url`<br />`properties.url` | `event_source_url` |
| `traits.firstName`<br />`traits.firstname`<br />`traits.first_name`<br />`context.traits.firstName`<br />`context.traits.firstname`<br />`context.traits.first_name`<br /> <span style="color: #4D4DFF;font-size:12px;">Transformed and sent as hashed value by RudderStack.</span> | `user_data.fn` |
| `traits.lastName`<br />`traits.lastname`<br />`traits.last_name`<br />`context.traits.lastName`<br />`context.traits.lastname`<br />`context.traits.last_name`<br /> <span style="color: #4D4DFF;font-size:12px;">Transformed and sent as hashed value by RudderStack.</span> | `user_data.ln` |
| `traits.address.city`<br />`context.traits.address.city`<br /> <span style="color: #4D4DFF;font-size:12px;">Transformed and sent as hashed value by RudderStack.</span> | `user_data.ct` |
| `traits.email`<br />`context.traits.email`<br />`properties.email`<br /> <span style="color: #4D4DFF;font-size:12px;">Transformed and sent as hashed value by RudderStack.</span> | `user_data.em` |
| `traits.phone`<br />`context.traits.phone`<br />`properties.phone`<br /> <span style="color: #4D4DFF;font-size:12px;">Transformed and sent as hashed value by RudderStack.</span> | `user_data.ph` |
| `traits.gender`<br />`context.traits.gender`<br /> <span style="color: #4D4DFF;font-size:12px;">Transformed and sent as hashed value by RudderStack.</span> | `user_data.ge` |
| `traits.state`<br />`context.traits.state`<br /> <span style="color: #4D4DFF;font-size:12px;">Transformed and sent as hashed value by RudderStack.</span> | `user_data.st` |
| `traits.country`<br />`context.traits.country`<br /> <span style="color: #4D4DFF;font-size:12px;">Transformed and sent as hashed value by RudderStack.</span> | `user_data.country` |

{{% /tab %}}
{{% tab tabName="API v2" %}}

Click the relevant event to understand how RudderStack tracks the event properties and maps them to the corresponding Snapchat Conversion properties:

{{< details "**Checkout Started**" >}}
<br/>

| RudderStack property | Snapchat Conversion property |
|:--------------------------------|:-----------------------|
| `properties.order_id` <br /> `properties.orderId` | `transaction_id` |
| `properties.category` | `item_category` |
| `properties.quantity` <br /> `properties.number_items` | `number_items` |
| `properties.currency` | `currency` |
| `properties.search_string` | `search_string` |
| `properties.client_dedup_id` |  `client_dedup_id` |
| `properties.price`<br />`properties.value`<br />`properties.revenue` |  `price` |

{{< /details >}}

{{< details "**Order Completed**" >}}
<br/>

| RudderStack property | Snapchat Conversion property |
|:--------------------------------|:-----------------------|
| `properties.order_id` <br /> `properties.orderId` | `transaction_id` |
| `properties.category` <br /> `properties.item_category` | `item_category` |
| `properties.quantity` <br /> `properties.number_items` | `number_items` |
| `properties.currency` | `currency` |
| `properties.client_dedup_id` | `client_dedup_id` |
| `properties.price`<br />`properties.value`<br />`properties.revenue` |  `price` |

{{< /details >}}

{{< details "**Payment Info Entered**" >}}
<br/>

| RudderStack property | Snapchat Conversion property |
|:--------------------------------|:-----------------------|
| `properties.checkout_id` <br /> `properties.transactionId` | `transaction_id` |
| `properties.item_ids` | `item_ids` |
| `properties.category`  |  `item_category` |
| `properties.quantity` <br /> `properties.number_items` | `number_items` |
| `properties.currency` | `currency` |
| `properties.search_string` | `search_string` |
| `properties.client_dedup_id` | `client_dedup_id` |
| `properties.price`<br />`properties.value`<br />`properties.revenue` | `price` |
| `properties.signUpMethod`<br />`properties.sign_up_method` | `sign_up_method` |
| `properties.client_dedup_id` | `client_dedup_id` |

{{< /details >}}

{{< details "**Product Added**" >}}
<br/>

| RudderStack property | Snapchat Conversion property |
|:--------------------------------|:-----------------------|
| `properties.transaction_id` <br /> `properties.transactionId` | `transaction_id` |
| `properties.product_id` | `item_ids` |
| `properties.category`  | `item_category` |
| `properties.quantity` <br /> `properties.number_items` | `number_items` |
| `properties.currency` | `currency` |
| `properties.search_string` | `search_string` |
| `properties.client_dedup_id` |  `client_dedup_id` |
| `properties.price`<br />`properties.value`<br />`properties.revenue` |   `price` |
| `properties.signUpMethod`<br />`properties.sign_up_method` |`sign_up_method` |
| `properties.client_dedup_id` | `client_dedup_id` |

{{< /details >}}

{{< details "**Product Added to Wishlist**" >}}
<br/>

| RudderStack property | Snapchat Conversion property |
|:--------------------------------|:-----------------------|
| `properties.transaction_id` <br /> `properties.transactionId` | `transaction_id` |
| `properties.product_id` | `item_ids` |
| `properties.category`  | `item_category` |
| `properties.quantity` <br /> `properties.number_items` | `number_items` |
| `properties.currency` | `currency` |
| `properties.search_string` | `search_string` |
| `properties.client_dedup_id` |  `client_dedup_id` |
| `properties.price`<br />`properties.value`<br />`properties.revenue` |   `price` |
| `properties.signUpMethod`<br />`properties.sign_up_method` |`sign_up_method` |
| `properties.client_dedup_id` | `client_dedup_id` |

{{< /details >}}

{{< details "**Product List Viewed**" >}}
<br/>

| RudderStack property | Snapchat Conversion property |
|:--------------------------------|:-----------------------|
| `properties.transaction_id` <br /> `properties.transactionId` | `transaction_id` |
| `properties.product_id` | `item_ids` |
| `properties.category`  | `item_category` |
| `properties.quantity` <br /> `properties.number_items` | `number_items` |
| `properties.currency` | `currency` |
| `properties.search_string` | `search_string` |
| `properties.client_dedup_id` |  `client_dedup_id` |
| `properties.price`<br />`properties.value`<br />`properties.revenue` |   `price` |
| `properties.signUpMethod`<br />`properties.sign_up_method` |`sign_up_method` |
| `properties.client_dedup_id` | `client_dedup_id` |

{{< /details >}}

{{< details "**Product Viewed**" >}}
<br/>

| RudderStack property | Snapchat Conversion property |
|:--------------------------------|:-----------------------|
| `properties.transaction_id` <br /> `properties.transactionId` | `transaction_id` |
| `properties.product_id` | `item_ids` |
| `properties.category`  | `item_category` |
| `properties.quantity` <br /> `properties.number_items` | `number_items` |
| `properties.currency` | `currency` |
| `properties.search_string` | `search_string` |
| `properties.client_dedup_id` |  `client_dedup_id` |
| `properties.price`<br />`properties.value`<br />`properties.revenue` |   `price` |
| `properties.signUpMethod`<br />`properties.sign_up_method` |`sign_up_method` |
| `properties.client_dedup_id` | `client_dedup_id` |

{{< /details >}}

{{< details "**Products Searched**" >}}
<br/>

| RudderStack property | Snapchat Conversion property |
|:--------------------------------|:-----------------------|
| `properties.transaction_id` <br /> `properties.transactionId` | `transaction_id` |
| `properties.query` <br />`properties.search_string` | `search_string` |
| `properties.item_ids` | `item_ids` |
| `properties.category`  | `item_category` |
| `properties.quantity` <br /> `properties.number_items` | `number_items` |
| `properties.currency` | `currency` |
| `properties.client_dedup_id` |  `client_dedup_id` |
| `properties.price`<br />`properties.value`<br />`properties.revenue` |   `price` |
| `properties.signUpMethod`<br />`properties.sign_up_method` |`sign_up_method` |
| `properties.client_dedup_id` | `client_dedup_id` |

{{< /details >}}

{{< details "**Promotion Clicked**" >}}
<br/>

| RudderStack property | Snapchat Conversion property |
|:--------------------------------|:-----------------------|
| `properties.transaction_id` <br /> `properties.transactionId` | `transaction_id` |
| `properties.item_ids` | `item_ids` |
| `properties.category`  | `item_category` |
| `properties.quantity` <br /> `properties.number_items` | `number_items` |
| `properties.currency` | `currency` |
| `properties.search_string` | `search_string` |
| `properties.client_dedup_id` |  `client_dedup_id` |
| `properties.price`<br />`properties.value`<br />`properties.revenue` |   `price` |
| `properties.signUpMethod`<br />`properties.sign_up_method` |`sign_up_method` |
| `properties.client_dedup_id` | `client_dedup_id` |

{{< /details >}}

{{< details "**Promotion Viewed**" >}}
<br/>

| RudderStack property | Snapchat Conversion property |
|:--------------------------------|:-----------------------|
| `properties.transaction_id` <br /> `properties.transactionId` | `transaction_id` |
| `properties.item_ids` | `item_ids` |
| `properties.category`  | `item_category` |
| `properties.quantity` <br /> `properties.number_items` | `number_items` |
| `properties.currency` | `currency` |
| `properties.search_string` | `search_string` |
| `properties.client_dedup_id` |  `client_dedup_id` |
| `properties.price`<br />`properties.value`<br />`properties.revenue` |   `price` |
| `properties.signUpMethod`<br />`properties.sign_up_method` |`sign_up_method` |
| `properties.client_dedup_id` | `client_dedup_id` |

{{< /details >}}

{{< details "**Signup**" >}}
<br/>

| RudderStack property | Snapchat Conversion property |
|:--------------------------------|:-----------------------|
| `properties.signUpMethod`<br />`properties.sign_up_method` |`sign_up_method` |
| `properties.transaction_id` <br /> `properties.transactionId` | `transaction_id` |
| `properties.item_ids` | `item_ids` |
| `properties.category`  | `item_category` |
| `properties.quantity` <br /> `properties.number_items` | `number_items` |
| `properties.currency` | `currency` |
| `properties.search_string` | `search_string` |
| `properties.client_dedup_id` |  `client_dedup_id` |
| `properties.price`<br />`properties.value`<br />`properties.revenue` |   `price` |

| `properties.client_dedup_id` | `client_dedup_id` |

{{< /details >}}

{{< details "**Other mappings**" >}}
<br/>

| RudderStack property | Data type | Snapchat Conversion property |
|:--------------------------------|:---- | :----------------------|
| `properties.description`  | String | `description` |
| `properties.brands` | Array of brands | `brands` | 
| `properties.event_tag` | String | `event_tag` |
| `properties.click_id` | String | `click_id` |
| `properties.level` | String | `level` |
| `properties.uuid_c1` | String | `uuid_c1` |
| `properties.customer_status` <br /> <span style="color: #4D4DFF;font-size:12px;">Can be one of `new`, `returning`, or `activated`.</span>  | String | `customer_status` | 
| `properties.data` | String | `data` |
| `properties.att_status` <br /> <span style="color: #4D4DFF;font-size:12px;">Can be one of `AUTHORIZED`, `RESTRICTED`, or `NOT_DETERMINED`.</span> | String | `att_status` |
| `properties.sign_up_method` | String | `sign_up_method` |
| `properties.advertiser_cookie_1` | String | `advertiser_cookie_1` |
| `properties.delivery_method` <br /> <span style="color: #4D4DFF;font-size:12px;">Can be one of `in_store`, `curbside`, or `delivery`.</span> | String | `delivery_method` | 
| `properties.eventConversionType` | String | `event_conversion_type` |
| `context.device.model` | String | `device_model` |
| `traits.country` <br /> `context.traits.country` | String | `country` |
| `traits.region` <br /> `context.traits.region` | String | `region` | 
| `context.userAgent` | String | `user_agent` | 
| `traits.firstName` <br /> `traits.firstname` <br /> `traits.first_name` <br /> `context.traits.firstName` <br />`context.traits.firstname`<br />`context.traits.first_name` | String |`hashed_first_name_sha` |
| `traits.middleName` <br /> `traits.middlename` <br /> `traits.middle_name` <br /> `context.traits.middleName` <br />`context.traits.middlename`<br />`context.traits.middle_name` | String |`hashed_middle_name_sha` |
| `traits.lastName` <br /> `traits.lastname` <br /> `traits.last_name` <br /> `context.traits.lastName` <br />`context.traits.lastname`<br />`context.traits.last_name` | String |`hashed_last_name_sha` |
| `traits.address.city`<br />`context.traits.address.city` | String | `hashed_city_sha` |
| `traits.state` <br /> `context.traits.state` | String | `hashed_state_sha` |
| `traits.zipcode` <br /> `context.traits.zipcode` <br /> `traits.zip` <br /> `context.traits.zip` | String | `hashed_zip` |
{{< /details >}}

{{% /tab %}}
{{< /tabs >}}

### `extinfo` mapping

This section lists the mappings for the [`extinfo` object](https://developers.snap.com/api/marketing-api/Conversions-API/Parameters#extinfo).

| RudderStack property | <div style="width:300px">`extinfo` index</div>  | 
| :----| :-----| 
| `context.device.type` | `0` <br /><br />RudderStack **automatically sets** the value to `i2` for Apple or `a2` for Android, depending on the source. |
| `context.app.namespace` | `1` |
| `context.app.build` | `2` |
| `context.app.version` | `3` |
| `context.device.model` | `4` |
| `context.locale` | `5` |
| `moment().tz(context.timezone)?.format('z');` | `6` <br /><br />See [Moment Timezone documentation](https://momentjs.com/timezone/docs/) for more information. RudderStack uses this package to get the timezone abbreviation string. | 
| `context.network.carrier` | `7` |
| `context.screen.width` | `8` |
| `context.screen.height` | `9` |
| `context.screen.density` | `10` |
| `properties.cpu_cores` | `11` |
| `properties.storage` | `12` |
| `properties.free_storage` | `13` |
| `context.timezone` | `14` |

{{< info >}}
If a value for any of the above properties is missing in the event, then RudderStack sets the corresponding `extinfo` index to an empty string.
{{< /info >}}

## Page

You can use the [`page`]({{< ref "event-spec/standard-events/page.md" >}}) call to record your website's page views, with any additional relevant information about the viewed page.

{{< warning >}}
RudderStack processes `page` calls as [`track`](#track) calls with the Snapchat event set to `page_view`. 

Hence, all the required fields for `track` events are required here as well.
{{< /warning >}}

A sample `page` call sent to Snapchat is shown below:

```javascript
rudderanalytics.page("Help", "Help Page", {
  name: "Contact Customer Care",
  request_ip: "203.0.113.0",
  context: {
    userAgent: "ABC"
  }
})
```