diff --git a/src/connections/destinations/catalog/actions-webhook-extensible/amazon-ads-integration-recipe.md b/src/connections/destinations/catalog/actions-webhook-extensible/amazon-ads-integration-recipe.md new file mode 100644 index 0000000000..6e9a923e6f --- /dev/null +++ b/src/connections/destinations/catalog/actions-webhook-extensible/amazon-ads-integration-recipe.md @@ -0,0 +1,146 @@ +--- +title: Amazon Ads Audience Sync Integration Recipe + +--- + +This recipe will guide you through how to set up a custom destination for Amazon Ads using Twilio Segment's Extensible Webhooks feature and how to sync customer data into an Audience list. By following these steps, you can integrate your data source with Amazon Ads. + +## Prerequisites + +To integrate Amazon Ads with Segment, ensure you have the following: + +- A Segment Account: an account with the Extensible Webhooks feature enabled (private beta access). +- An Amazon Ads Account: an active account or API access to Amazon Ads. +- Authentication Credentials: the necessary credentials for authentication. These are OAuth endpoints, Client ID, Secret, Scopes. +- Data mapping information: Knowledge of the data fields required by Amazon Ads. + +## Getting started + +### 1. Set up the Extensible Webhook destination + +To set up your destination in Segment: + +1. In your Segment workspace go to **Catalog** > **Destinations**. +2. Search for Extensible Webhook and select **Add destination**. + +### 2. Select the data source + +1. Choose the source from which you want to send data to Amazon Ads. +2. Click **Next** to proceed. + +### 3. Specify the instance details + +1. Enter a recognizable name for your webhook instance (e.g., "Segment to Amazon Integration"). +2. (Optional) Add a brief description of the integration. + +### 4. Select the authentication type + +An Amazon Client Application has to be created which requires approval. For steps on how to complete Amazon API onboarding, see the [Amazon documentation](https://advertising.amazon.com/API/docs/en-us/guides/onboarding/overview){:target="_blank"}. + +The LwA (Login with Amazon) application that you create should have `advertising::audiences` as the scope. For Campaign management, like marking conversions, the scope should be `advertising::campaign_management`. + +Once a LwA app has been created, you will need to add the redirect URI “https://app.segment.com/oauth-service/webhook/callback” to the list of Allowed Return URLs. For more detail on this, see the [Amazon documentation](https://advertising.amazon.com/API/docs/en-us/guides/get-started/create-authorization-grant#allow-a-return-url){:target="_blank"}. + +Note down the Client ID and Secret, available in the Login with Amazon section on the [Amazon Developer site](https://developer.amazon.com/){:target="_blank"}. These will be used to set up authentication with Segment. + +#### Authentication + +To set up authentication: +1. Select OAuth 2.0 from the list of options and select **Authorization Code**. +2. Enter the following credential details as listed below or given in the web app: + - Client ID + - Client secret + - Authorize URL: https://www.amazon.com/ap/oa + - Token URL: https://api.amazon.com/auth/o2/token + - Refresh URL: https://api.amazon.com/auth/o2/token + - Scope: `advertising::audiences` + + The authorization URL can be found [here](https://advertising.amazon.com/API/docs/en-us/guides/get-started/create-authorization-grant#determine-the-url-prefix-for-your-region){:target="_blank"} and the access/refresh token URL can be found [here](https://advertising.amazon.com/API/docs/en-us/guides/get-started/retrieve-access-token#call-the-authorization-url-to-request-access-and-refresh-tokens){:target="_blank"}, depending on your region. + +3. Once you create the destination instance, you will then be redirected to the Settings section. Click **Connect** to set up the OAuth connection with Amazon Ads. +4. You will be redirected to Amazon Ads. Log in and click **Allow** to complete the authentication flow. + +Once done redirected back to the destination settings page, authentication is completed and you’re now ready to send events to Amazon Ads. + +### 5. Perform Data Mapping + +#### Data transformation + +Amazon Ads expects data to be in a certain format with nested fields. This format cannot be mapped with the mappings functionality and will need to be transformed within an insert function. + +You will need to write an insert function that appends a property, for example one called “body”, to the event which would then have nested fields. For the Amazon Ads Audience API, a sample expected payload is of the following structure: + +``` +{ + "records": [ + { + "hashedPII": [ + { + "firstname": "sdstdsdsaring", + "address": "scdcadscstring", + "phone": "sadtrdsaidng", + "city": "ssatring", + "state": "strccaing", + "postal": "staccaring", + "email": "stracaing", + "lastname": "stacaddacring" + } + ], + "externalUserId": "A12346sgd", + "action": "CREATE" + } + ], + "targetResource": { + "connectionId": "", + "targetTypes": [ + "DSP" + ] + }, + "audienceId": 371552318001631924 +} +``` + +The Amazon Ads Audience API's expected fields are: +- `Records` is an array of objects. For the beta, Segment doesn’t support batching to iterate over this object yet. The required parameters are: + - `hashedPII`: A list of SHA-256 hashed PII that will be matched with Amazon entities. + - `firstname` + - `lastname` + - `address` + - `phone` + - `city` + - `state` + - `postal` + - `email` + - `externalUserId`: The id used by external systems to identify customers. + - `action`: Can be “CREATE” or “DELETE” based on whether you want to add or remove the user from the list. +- `audienceID` is the ID of the Audience list to which the data should be either added or deleted. You can get the audienceID from within the Amazon Ads console or when creating an Audience from the API. + +#### Data Mapping + +1. Create a new Mapping in the Mappings tab and select the **Send** HTTP action. +2. Choose which events you want to send to Amazon Ads Audience API using the Event filters. +3. Fill out mapping fields: + - Specify the URL: + - The API endpoint is based on region. + - Include the suffix with the Audience API Endpoint: /amc/audiences/records + - Specify the headers: + - `Amazon-Advertising-API-ClientId`: The Client ID from Login with Amazon Account. +4. Use the mapping interface and search for the “body” parameter that was created in the insert function to select the transformed object that can be sent as the event body. +5. Turn off batching for this operation. + +### 6. Test the output and connection + +1. Click **Test Connection** to send a sample payload. +2. In Amazon Ads, verify that the test data has been received and processed correctly. + +#### Troubleshooting + +If the test fails: +- review the authentication details and data mappings. +- check for error messages in Segment and Amazon Ads. + +### 7. Save and enable the destination + +1. Once the test is successful, click **Save** to store your configuration. +2. Toggle the destination to Enable to start sending live data to Amazon Ads Audience API. +3. Monitor the data flow to ensure that events are being delivered as expected. diff --git a/src/connections/destinations/catalog/actions-webhook-extensible/google-search-ads-integration-recipe.md b/src/connections/destinations/catalog/actions-webhook-extensible/google-search-ads-integration-recipe.md new file mode 100644 index 0000000000..e6872cd7a4 --- /dev/null +++ b/src/connections/destinations/catalog/actions-webhook-extensible/google-search-ads-integration-recipe.md @@ -0,0 +1,113 @@ +--- +title: Google Search Ads 360 Conversion API Integration Recipe +--- + +This recipe will guide you through how to set up a custom destination for Google Search Ads 360 conversions using Twilio Segment’s Extensible Webhooks feature. + +## Prerequisites + +To integrate Search Ads 360 with Twilio Segment, ensure you have the following: + +- A Segment account: an account with the Extensible Webhooks feature enabled (private beta access). +- A Search Ads account: an active account and API access to Google Search Ads 360. +- Authentication credentials: necessary credentials for authentication, for example, API keys and tokens. +- Data mapping information: knowledge of the data fields required by Search Ads 360. + +## Getting started + +### 1. Configure Extensible Webhook as a destination + +1. In your Segment workspace, navigate to **Connections** > **Catalog** > **Destinations**. +2. Use the search bar to search for **Extensible Webhook** and select **Add destination**. + +### 2. Select the data source + +1. Choose the source that you want to send data from to Google Search Ads 360. +2. Click **Next** to proceed. +3. Give your destination a name and create your destination. + +### 3. Specify the instance details + +1. Enter a recognizable name for your webhook instance, for example, Segment to Search Ads Integration. +2. (Optional) Add a brief description of the integration. + +### 4. Select the authentication type + +As a prerequisite to authenticate APIs, you need to create OAuth credentials. Once generated, note down the Client ID and Secret. They are required to set up authentication between Segment and Google Search Ads. + +You will also need to add the following redirect URI to the list of allowed return URLs: https://app.segment.com/oauth-service/webhook/callback. + +#### Authentication + +1. Select OAuth 2.0 and select Authorization Code. +2. Enter the following credentials details from your project: + - Client ID + - Client secret + - Authorize URL: https://accounts.google.com/o/oauth2/v2/auth + - Token URL: https://oauth2.googleapis.com/token + - Refresh URL: https://oauth2.googleapis.com/token + - Scope: https://www.googleapis.com/auth/doubleclicksearch +3. Once you have created the destination instance, you will be redirected to the Settings section. Click **Connect** to set up the OAuth connection with Google Search Ads 360. +4. Log in to your Google Search Ads account and click **Allow** to complete authentication. + +If authentication is completed successfully, you will be redirected to the destination settings page. At this point, you are ready to send events to Google Search Ads. + +### 5. Data mapping + +#### Data transformation + +Google Search Ads 360 expects data to be in a certain format with nested fields. This format cannot be mapped with the mappings functionality and will need to be transformed within an insert function. + +You will need to write an insert function that appends a property, for example one called “body”, to the event which would then have nested fields. For the Google Search Ads 360 Conversion API, an expected sample payload is of the following structure: + +``` +{ + "kind": "doubleclicksearch#conversionList", + "conversion" : [{ + "clickId" : "COiYmPDTv7kCFcP0KgodOzQAAA", // Replace with a click ID from your site + "conversionId" : "test_20130906_04", + "conversionTimestamp" : "1378710000000", + "segmentationType" : "FLOODLIGHT", + "segmentationName" : "Test", + "type": "TRANSACTION", + "revenueMicros": "10000000", // 10 million revenueMicros is equivalent to $10 of revenue + "currencyCode": "USD" + }] + } +``` + +The Google Search Ads 360 Conversion API's required fields are: +- `kind` which is "doubleclicksearch#conversionList". Conversion is an array. For the beta, Segment doesn’t support batching to iterate over this. +- `clickId` which is the ID of a specific click on an ad that the customer clicked on. +- `conversionId` is a unique ID that tracks the particular conversion. +- `conversionTimestamp` is date and time in epoch milliseconds on when the conversion took place. +- `segmentationType` should be floodlight. +- `segmentationName` is the floodlight activity to report this conversion to. +- `type` which can be `Action` or `Transaction` to indicate whether the conversion had a monetary value or not. + +#### Data mapping + +1. Create a new Mapping in the Mappings tab and select the **Send** HTTP action. +2. Choose which events you want to send to Google Search Ads 360 API using the Event filters. +3. Fill out mapping fields: + - Specify the URL: https://www.googleapis.com/doubleclicksearch/v2/conversion +4. Use the mapping interface and search for the “body” parameter that was created in the insert function to select the transformed object that can be sent as the event body. +5. Turn off batching for this operation. + +### 6. Test the output and connection + +1. Click **Test Connection** to send a sample payload. +2. In Google Search Ads 360 Conversion, verify that the test data has been received and processed correctly. + +#### Troubleshooting + +If the test fails: +- review the authentication details and data mappings. +- check for error messages in Segment and Search Ads. + +### 7. Save and enable the destination + +1. Once the test is successful, click **Save** to store your configuration. +2. Toggle the destination to Enable to start sending live data to Google Search Ads 360 Conversion API. +3. Monitor the data flow to ensure that events are being delivered as expected. + diff --git a/src/connections/destinations/catalog/actions-webhook-extensible/microsoft-integration-recipe.md b/src/connections/destinations/catalog/actions-webhook-extensible/microsoft-integration-recipe.md new file mode 100644 index 0000000000..b04ee6b7aa --- /dev/null +++ b/src/connections/destinations/catalog/actions-webhook-extensible/microsoft-integration-recipe.md @@ -0,0 +1,113 @@ +--- +title: Microsoft Dynamics 365 (Sales Hub) Integration Recipe +--- + +This recipe will guide you through how to set up a custom destination for Microsoft Dynamics 365 (Sales) using Twilio Segment’s Extensible Webhook feature. + +## Prerequisites + +To integrate Microsoft Dynamics 365 with Twilio Segment, ensure you have the following: + +- A Segment account: an account with the Extensible Webhooks feature enabled (private beta access). +- An Azure application: an Azure application is required for authentication. +- Authentication credentials: necessary credentials for authentication, for example, endpoints and scopes. +- Data mapping information: knowledge of the data fields required by Microsoft Dynamics 365. + +## Getting started + +### 1. Configure Extensible Webhook as a destination + +1. In your Segment workspace, navigate to **Connections** > **Catalog** > **Destinations**. +2. Use the search bar to search for "Extensible Webhook" and select **Add destination**. + +### 2. Select the data source + +1. Choose the source that you want to send data from to Microsoft Dynamics 365.. +2. Click **Next** to proceed. +3. Give your destination a name and create your destination. + +### 3. Specify the instance details + +1. Enter a recognizable name for your webhook instance, for example, Segment to Microsoft Dynamics Integration. +2. (Optional) Add a brief description of the integration. + +### 4. Select the authentication type + +For authentication, you need to first create an Azure application that can authenticate users to provide access to Microsoft Dynamics API. See [Microsoft documentation](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app?tabs=client-secret){:target="_blank"} for details on how to create an application and how to get the client secret that will later be used for authentication. + +The redirect URI for your application is https://app.segment.com/oauth-service/webhook/callback. + +To connect the Azure app with the Dynamics instance, go to the Power Platform Admin Center. +Here you will need to create new app users associated with a business unit, and provide security roles. + +Once you have successfully created an Azure web application and associated it with a Dynamics environment, you can proceed to authentication in Segment. + +1. Navigate to the settings page of the webhook destination in Segment. +2. Select OAuth 2.0 and select Authorization Code. +3. Enter the following credential details from your web app or as listed below: + - Client ID + - Client secret + - Access Token URL: https://login.microsoftonline.com//oauth2/v2.0/token + - Scope: https:///.default +4. Click **Connect** to set up the OAuth connection with Microsoft. + +Authentication will take place if the configurations are correct and the access token will automatically be generated without the need for user login. + +### 5. Data mapping + +#### Data transformation (optional) + +Microsoft Dynamics 365 can create and update multiple entities all at once with a nested object structure. For example, with a single API call to the `accounts` entity, you can create a new account, contact and a related opportunity in a single shot. + +You will need to write an insert function that appends a property, for example one called “body”, to the event which would then have nested fields. For the Create New Account API, an expected sample payload is of the following structure: + +``` +{ + "name": "Sample Account", + "primarycontactid": + { + "firstname": "John", + "lastname": "Smith" + }, + "opportunity_customer_accounts": + [ + { + "name": "Opportunity associated to Sample Account", + "Opportunity_Tasks": + [ + { "subject": "Task associated to opportunity" } + ] + } + ] +} +``` + +The Create New Account API’s expected fields are listed in [Microsoft's documentation](https://learn.microsoft.com/en-us/power-apps/developer/data-platform/webapi/reference/account?view=dataverse-latest){:target="_blank"}. + +To create or update the Account entity only, you can skip this step and directly use mappings to map properties and keys. + +#### Data mapping + +1. Create a new Mapping in the Mappings tab and select the **Send** HTTP action. +2. Choose which events you want to send to Google Search Ads 360 API using the Event filters. +3. Fill out mapping fields: + - Specify the URL: [Organization URI]/api/data/v9.2/accounts (this is for creating new accounts) +4. Use the mapping interface and search for the “body” parameter that was created in the insert function to select the transformed object that can be sent as the event body. +5. Turn off batching for this operation. + +### 6. Test the output and connection + +1. Click **Test Connection** to send a sample payload. +2. In Microsoft Dynamics 365, verify that the test data has been received and processed correctly. + +#### Troubleshooting + +If the test fails: +- review the authentication details and data mappings. +- check for error messages in Segment and Search Ads. + +### 7. Save and enable the destination + +1. Once the test is successful, click **Save** to store your configuration. +2. Toggle the destination to Enable to start sending live data to Microsoft Dynamics 365. +3. Monitor the data flow to ensure that events are being delivered as expected. \ No newline at end of file diff --git a/src/connections/destinations/catalog/actions-webhook-extensible/reddit-ads-audience-integration-recipe.md b/src/connections/destinations/catalog/actions-webhook-extensible/reddit-ads-audience-integration-recipe.md new file mode 100644 index 0000000000..98e4b6435b --- /dev/null +++ b/src/connections/destinations/catalog/actions-webhook-extensible/reddit-ads-audience-integration-recipe.md @@ -0,0 +1,130 @@ +--- +title: Reddit Ads (Audience) Integration Recipe +--- + +This recipe will guide you through setting up a custom destination for Reddit Ads (Audiences) using Twilio Segment's Extensible Webhooks feature. By following these steps, you will be able to integrate your data source with Reddit Ads (Audiences). + +## Prerequisites + +To integrate Reddit Ads with Segment, ensure you have the following: + +A Segment account: an account with the Extensible Webhooks feature enabled (private beta access). +A Reddit Ads (Audiences) account: an active account or API access to Reddit Ads (Audiences). +Authentication credentials: necessary credentials for authentication, for example, API keys and tokens. +Data mapping information: knowledge of the data fields required by Reddit Ads (Audiences). + +## Getting started + +### 1. Configure Extensible Webhook as a destination + +1. In your Segment workspace, navigate to **Connections** > **Catalog** > **Destinations**. +2. Use the search bar to search for **Extensible Webhook** and select **Add destination**. + +### 2. Select the data source + +1. Choose the source that you want to send data from to Reddit Ads (Audiences). +2. Click **Next** to proceed. +3. Give your destination a name and create your destination. + +### 3. Specify the instance details + +In Reddit Ads, create an app. For steps on how to do this, see the [Reddit documentation](https://ads-api.reddit.com/docs/v3/#create-a-developer-application){:target="_blank"}. + +When creating your app, specify the following details: + +- Name: Give your webhook instance a recognizable name. +- Description (optional): Add a brief description of the integration. +- Endpoint URL: Provide the webhook URL or endpoint provided by Reddit Ads (Audiences). + +> info: Redirect URI +The redirect URI used when creating a Reddit web app is “https://app.segment.com/oauth-service/webhook/callback”. + +### 4. Select the authentication type + +Reddit provides developers with an option to create a web application to set up OAuth 2.0 for the Ads API to be authenticated. Once a web app has been created, you will need to note down the Client ID and Secret provided by Reddit. These will be used to set up authentication on Segment. + +To set up OAuth: + +1. Go to **Authentication Method** and select **OAuth 2.0**. +2. Enter the following credentials as required: + - Client ID: provided by the Reddit web app + - Secret: provided by the Reddit web app + - Authorize URL: https://www.reddit.com/api/v1/authorize + - Token URL: https://www.reddit.com/api/v1/access_token + - Refresh URL: https://www.reddit.com/api/v1/access_token + - Scope: To update Audiences, you will need to add ‘adsedit’ as a scope. To add multiple scopes, separate the values by commas. + +You can also find the Authorize URL, Token URL, and Refresh URL in the [Reddit documentation](https://ads-api.reddit.com/docs/v3/operations/Update%20Custom%20Audience%20Users){:target="_blank"}. + +3. Once you create the destination instance, you will be redirected to Settings. Click on **Connect** to set up the OAuth connection with Reddit and you’ll be redirected to reddit. Click on “Allow” to complete the authentication flow. +4. Once you’re redirected back to the destination settings page, this means that authentication is completed and you’re now ready to send events to Reddit. + +### 5. Perform data mapping + +#### Data transformation + +The Reddit Custom Audience API expects data in a nested format. To format the payload correctly, you will have to write an insert function that appends a new property called “body” (for example). + +This will have the following structure: + +``` +{ + "data": { + "action_type": "ADD", + "column_order": [ + "EMAIL_SHA256", + "MAID_SHA256" + ], + "user_data": [ + [ + "d7ef2e7b2a3663c25284a3d6d13b1ca727fc8c659474b81afe0cec997a4737d2", + "510870d7b3e47a28a2b2f3aef27a4c81aab0b2eefda27dea50bc4c991d9e5435" + ] + ] + } +} +``` + +The required parameters are: + +- `action_type` which can take values “ADD” or “REMOVE” depending on whether a customer has to be added or removed from the list. +- `column_order` which can take two values, “EMAIL_SHA256” and “MAID_SHA256”. The order indicates the column order of the data being synced inside `user_data` +- `user_data` is an array of values which has hashed email id or MAID id or both. For the beta, Segment doesn’t support batching to iterate just over this array yet. + +#### Data mapping + +In this recipe, as an example, users are added to the existing audience but you can use one or multiple mappings to perform any `Put`, `Patch` or `Post` action types. + +1. Create a new mapping from the **Mappings** tab, click on **Add Mapping** and select the “Send” HTTP action. +2. Select events to send. Define the event triggers to send to Reddit Ads (Audiences) using the event filters. +3. Fill out mapping fields: + 1. Specify the URL and method. + - For example, using the following URL: https://ads-api.reddit.com/api/v3/custom_audiences/{audience_id}/users + 1. Replace `audience_id` with the actual audience ID you want to edit. You can find the iID below the name of the Audience List to be modified on Audience Manager. + 2. Select `PATCH` as the HTTP method. The API expects a Patch operation on the endpoint. +4. Use the mapping interface and search for the “body” parameter that was created in the insert function to select the transformed object that can be sent as the event body. +5. Turn off batching for this operation. + +Reddit supports three types of actions that can be performed via Extensible Webhook. + +- Audiences + - Manage Audiences: Create a new audience or manage existing ones. + - Manage Audience Users: PATCH users in existing audiences or create a new audience and add users to it. +- Campaigns + - Manage Campaigns: Create a new campaign or manage existing ones. + +### 6. Test the output and connection + +1. Click **Test Connection** to send a sample payload. +2. Verify in Reddit Ads (Audiences) that the test data has been received and processed correctly. + +Troubleshooting: + +- If the test fails, review the authentication details and data mappings. +- Check for error messages in Segment and Reddit Ads (Audiences). + +### 7. Save and enable the destination + +1. Once the test is successful, click **Save** to store your configuration. +2. Toggle the destination to Enabled to start sending live data. +3. Monitor the data flow to ensure events are being delivered as expected. diff --git a/src/connections/destinations/catalog/actions-webhook-extensible/reddit-ads-conversion-api-integration-recipe.md b/src/connections/destinations/catalog/actions-webhook-extensible/reddit-ads-conversion-api-integration-recipe.md new file mode 100644 index 0000000000..f92a635228 --- /dev/null +++ b/src/connections/destinations/catalog/actions-webhook-extensible/reddit-ads-conversion-api-integration-recipe.md @@ -0,0 +1,155 @@ +--- +title: Reddit Ads Conversion API Integration Recipe +--- + +This recipe will guide you through setting up a custom destination for Reddit Ads Conversion API using Segment’s Extensible Webhooks feature. By following these steps, you can integrate your data source with Reddit Ads Conversion API without writing any code. + +## Prerequisites + +To integrate Reddit Ads Conversion with Segment, ensure you have the following: + +- A Segment account: an account with the Extensible Webhooks feature enabled. +- Reddit Ads Conversion API account: an active account or API access to Reddit Ads Conversion API. +- Authentication credentials: necessary credentials for authentication, for example, API keys and tokens. +- Data mapping information: knowledge of the data fields required by Reddit Ads Conversion API. + +## Getting started + +### 1. Navigate to the Extensible Webhook destination + +1. In your Segment workspace, go to **Catalog** > **Destinations**. +2. Use the search bar to search for **Extensible Webhook** and select **Add destination**. + +### 2. Select the data source + +1. Choose the source that you want to send data from to Reddit Ads Conversion API. +2. Click **Next** to proceed. +3. Give your destination a name and create your destination. + +### 3. Specify the instance details + +In Reddit Ads, create an app. For steps on how to do this, see the [Reddit documentation](https://business.reddithelp.com/s/article/Create-a-Reddit-Application){:target="_blank"}. + +When creating your app, specify the following details: + +- Name: Give your webhook instance a recognizable name. +- Description (optional): Add a brief description of the integration. +- Endpoint URL: Provide the webhook URL or endpoint provided by Reddit Ads Conversion API. + +### 4. Select the authentication type + +Reddit provides two methods for authentication: +- Creating an app. +- Using the conversion access token. + +The conversion access token provides a bearer token that can be added to the header. To get the conversion access token from Reddit Ads: + +1. In your Reddit Ads account and navigate to **Events Manager**. +2. Select **Conversions API**. +3. Click **Generate Access Token** to generate your token. Copy and make a note of it. + +Once you have the conversion token, go back to your destination in your Segment workspace. In **Settings**, go to **Authorization Settings** and select “No Auth” as the authentication method. + +### 5. Perform data mapping + +#### Data transformation + +The Reddit Conversion API expects data in a nested format. To format the payload correctly, you will need to write an insert function that appends a new property, for example `body`. + +This will have the following structure: + +``` +{ + "events": [ + { + "click_id": "3184742045291813272", + "event_at": "2018-01-01T00:00:00Z", + "event_at_ms": 1514764800000, + "event_type": { + "tracking_type": "Purchase", + "custom_event_name": "string" + }, + "event_metadata": { + "item_count": 5, + "currency": "USD", + "value": 1099, + "value_decimal": 10.99, + "conversion_id": "H72B9A4YXQ", + "products": [ + { + "id": "item-213", + "name": "Carne Asada Burrito", + "category": "Food Items" + } + ] + }, + "user": { + "email": "snoo@example.com", + "external_id": "7c73f2ae-a433-4d7b-9838-f467da98f48e", + "uuid": "1684189007728.7c73f2ae-a433-4d7b-9838-f467da98f48e", + "ip_address": "192.0.2.1", + "user_agent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0", + "idfa": "EA7583CD-A667-48BC-B806-42ECB2B48606", + "aaid": "cdda802e-fb9c-47ad-9866-0794d394c912", + "opt_out": true, + "screen_dimensions": { + "width": 3440, + "height": 1440 + }, + "data_processing_options": { + "modes": [ + "LDU" + ], + "country": "US", + "region": "US-CA" + } + } + } + ] +} +``` + +The conversions payload consists of three core components: + +- `event_type`: This classifies the conversion event used for aggregating data in reporting. +- `event_metadata`: This contains information associated with specific actions or conversion events shared to Reddit. +- `user`: This includes attribution and advanced matching signals that improve conversion measurement. + +These components are separated into various parameters, some of which are required: +- `event_at` +- `tracking_type` +- `conversion_id` + +It’s also recommended that you include the `email`, `ip_address`, `uuid`, and `click_id` parameters. + +### Data mapping + +To map data from your destination to Reddit Ads: + +1. Create a new mapping in the **Mappings** tab, select the **Send** action. +2. Define the event trigger by selecting the events you want to send to Reddit Ads Conversion API using the Event name filters. +3. (Optional) Add enrichment entities as necessary. +4. Fill out mapping fields: + 1. To specify the URL, go to your Reddit Ads account, navigate to **Pixel configuration** to find your Pixel ID. The format of the URL should be https://ads-api.reddit.com/api/v2.0/conversions/events/{{YOURPICEL_ID}} + 2. Specify the headers. + - Set up Authorization using the Bearer Token generated in the previous step. + - Specify the Content Type that the Conversion API expects. +5. Use the mapping interface and search for the “body” parameter that was created in the insert function to select the transformed object that can be sent as the event body. +6. Turn off batching for this operation. + +### 6. Test the output and connection + +1. Click **Test Connection** to send a sample payload. +2. In the Reddit Ads Conversion API, verify that the test data has been received and processed correctly. + +#### Troubleshooting + +If the test fails: +- Review the authentication details and data mappings. +- Check for error messages in Segment and the Reddit Ads Conversion API. + +### 7. Save and enable the destination + +1. Once the test is successful, click **Save** to store your configuration. +2. Toggle the destination to Enable to start sending live data to Reddit Ads Conversion API. +3. Monitor the data flow to ensure that events are being delivered as expected.