OpenAI Ads Cloud Mode Integration

Send events to OpenAI Ads using RudderStack cloud mode.

4 minute read

After you have successfully instrumented OpenAI Ads as a destination in RudderStack, follow this guide to correctly send your events to OpenAI Ads in cloud mode.

Find the open source transformer code for this destination in the GitHub repository.

Track

Use the track call to send conversion events to OpenAI Ads.

A sample track call is shown below:

javascript

rudderanalytics.track("Order Completed", {
  orderId: "order-123",
  revenue: 49.99,
  currency: "USD",
  action_source: "web",
  source_url: "https://www.example.com/checkout/success",
  products: [
    {
      product_id: "sku-123",
      name: "T-shirt",
      category: "Apparel",
      quantity: 1,
      price: 49.99,
    },
  ],
});

Event mapping

RudderStack uses your event mapping settings to resolve the OpenAI Ads event type for each track event.

If a configured mapping matches the RudderStack event name, RudderStack sends the event to the mapped OpenAI Ads standard or custom event.
If no mapping matches and the RudderStack event name already matches a standard OpenAI Ads event ID, such as order_created, RudderStack sends it as that standard event.
If no mapping matches and the event name is not a standard OpenAI Ads event ID, RudderStack rejects the event.

Page

Use the page call to send web page view events to OpenAI Ads.

A sample page call is shown below:

javascript

rudderanalytics.page("Product", "Product Viewed", {
  url: "https://www.example.com/products/sku-123",
});

RudderStack resolves page events using your event mapping settings. Unmapped page events default to the OpenAI Ads page_viewed event.

Screen

Use the screen call to send mobile screen view events to OpenAI Ads through cloud mode.

A sample screen call is shown below:

javascript

rudderanalytics.screen("Home", "Home Viewed");

RudderStack resolves screen events using your event mapping settings. Unmapped screen events default to the OpenAI Ads page_viewed event.

Event data fields

RudderStack maps the following top-level event fields to OpenAI Ads:

RudderStack property	OpenAI Ads field	Notes
`properties.action_source` `properties.actionSource` Default action source setting	`action_source`	Optional. Supported values are `web`, `mobile_app`, `offline`, `physical_store`, `phone_call`, `email`, and `other`.
`properties.source_url` `properties.sourceUrl` `context.page.url`	`source_url`	Required when `action_source` is `web`.
`properties.oppref`	`oppref`	Optional OpenAI Ads reference value.
`properties.optOut` `properties.opt_out`	`opt_out`	Optional boolean value.

RudderStack maps the following event data fields:

RudderStack property	OpenAI Ads field	Notes
`properties.amount` `properties.value` `properties.revenue`	`data.amount`	Converted to the currency’s minor units when currency is available.
`properties.currency` Default currency setting	`data.currency`	Required when amount is present.
`properties.contents` `properties.products`	`data.contents`	Sent for `contents`, `plan_enrollment`, and custom event data shapes. Not sent for `customer_action` events.

For each item in properties.contents or properties.products, RudderStack maps the following fields:

RudderStack property	OpenAI Ads field
`id` `content_id` `contentId` `item_id` `itemId` `product_id` `productId` `sku`	`id`
`name` `title` `product_name` `productName`	`name`
`content_type` `contentType` `type` `category` `product_category`	`content_type`
`group_id` `groupId`	`group_id`
`variant_dict` `variantDict`	`variant_dict`
`quantity` `count`	`quantity`
`amount` `value` `price`	`amount`
`currency` `currency_code` `currencyCode`	`currency`

User matching fields

How RudderStack processes the following user matching fields depends on the Enable hashing setting:

RudderStack property	OpenAI Ads field
`traits.emails` `context.traits.emails` `traits.email` `context.traits.email`	`emails_sha256`
`traits.phoneNumbers` `context.traits.phoneNumbers` `traits.phone_numbers` `context.traits.phone_numbers` `traits.phones` `context.traits.phones` `traits.phone` `context.traits.phone`	`phone_numbers_sha256`
`userId` `anonymousId`	`external_ids_sha256`
`traits.firstNames` `context.traits.firstNames` `traits.first_names` `context.traits.first_names` `traits.firstName` `traits.first_name` `context.traits.firstName` `context.traits.first_name`	`first_names_sha256`
`traits.lastNames` `context.traits.lastNames` `traits.last_names` `context.traits.last_names` `traits.lastName` `traits.last_name` `context.traits.lastName` `context.traits.last_name`	`last_names_sha256`

Note that:

When Enable hashing is enabled (the default), send raw values in the source fields listed above. RudderStack normalizes and hashes the values and rejects apparent pre-hashed input.
When Enable hashing is disabled, each value supplied for these five *_sha256 fields must already be normalized and SHA-256 hashed. RudderStack does not normalize these values. If a supplied value isn’t hashed, RudderStack rejects it and the entire cloud mode event fails.

RudderStack lowercases every hash value it sends, whether it hashed the value itself or received it pre-hashed.

For external_ids_sha256, RudderStack uses userId when available and falls back to anonymousId. When hashing is disabled and userId is absent, RudderStack still hashes the SDK-generated anonymousId automatically because it isn’t pre-hashed.
RudderStack also forwards the following non-hashed matching fields when present: regions, postal_codes, cities, countries, obref, android_advertising_id, ip_address, and user_agent.

See the identifier normalization rules section for more information.

OpenAI Ads Cloud Mode Integration

Track

Event mapping

Page

Screen

Event data fields

User matching fields

Questions? Let's figure it out together.