OpenAI Ads Web Device Mode Integration

Send events to OpenAI Ads using RudderStack web device 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 web device mode.

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

OpenAI Ads supports device mode only for web sources. Mobile device mode is not supported. Mobile and other non-web source types use cloud mode only.

Add web device mode integration

The RudderStack JavaScript SDK loads the OpenAI Ads Measurement Pixel from https://bzrcdn.openai.com/sdk/oaiq.min.js and initializes it with your Pixel ID.

If you use a Content Security Policy (CSP) header on your website, allowlist the bzrcdn.openai.com domain for script loading.

Identify

Use the identify call to update the user data stored by the OpenAI Ads Measurement Pixel.

A sample identify call is shown below:

javascript

rudderanalytics.identify("user-123", {
  email: "alex@example.com",
  phone: "+15551234567",
  firstName: "Alex",
  lastName: "Keener",
  city: "San Francisco",
  state: "CA",
  country: "US",
  postalCode: "94105",
});

RudderStack maps identify traits to the OpenAI Ads Measurement Pixel user object as follows:

RudderStack property	OpenAI Ads user field	Notes
`traits.email` `context.traits.email`	`email_sha256`	Normalized and hashed by RudderStack when Enable hashing is enabled. Otherwise, the value must already be normalized and SHA-256 hashed.
`traits.phone` `context.traits.phone`	`phone_number_sha256`	Normalized and hashed by RudderStack when Enable hashing is enabled. Otherwise, the value must already be normalized and SHA-256 hashed.
`userId` `anonymousId`	`external_id_sha256`	Hashed by RudderStack when Enable hashing is enabled. When disabled, `userId` must already be SHA-256 hashed. RudderStack uses `userId` when available and falls back to `anonymousId`. If hashing is disabled and `userId` is absent, RudderStack still hashes `anonymousId` automatically.
`traits.firstName` `traits.first_name` `context.traits.firstName` `context.traits.first_name`	`first_name_sha256`	Normalized and hashed by RudderStack when Enable hashing is enabled. Otherwise, the value must already be normalized and SHA-256 hashed.
`traits.lastName` `traits.last_name` `context.traits.lastName` `context.traits.last_name`	`last_name_sha256`	Normalized and hashed by RudderStack when Enable hashing is enabled. Otherwise, the value must already be normalized and SHA-256 hashed.
`traits.city` `context.traits.city`	`city`	Sent as a plain value.
`traits.state` `context.traits.state`	`region`	Sent as a plain value.
`traits.postalCode` `context.traits.postalCode`	`postal_code`	Sent as a plain value.
`traits.country` `context.traits.country`	`country`	Sent as a plain value.

Note that:

When the Enable hashing setting is enabled (the default), send raw values in the five 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 the five *_sha256 fields must already be normalized and SHA-256 hashed. RudderStack does not normalize these values and lowercases accepted hashes.
If a supplied identifier isn’t hashed, RudderStack drops that identifier and logs an error in the browser console, but the event still fires. Unlike cloud mode, which fails the entire event, web device mode can therefore reduce match rates without an event failure.

See the identifier normalization rules section for more information.

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",
  products: [
    {
      product_id: "sku-123",
      name: "T-shirt",
      category: "Apparel",
      quantity: 1,
      price: 49.99,
    },
  ],
});

RudderStack uses your event mapping settings to resolve the OpenAI Ads event type for each track event. If no mapping matches the RudderStack event name, RudderStack does not send the event to the Measurement Pixel.

The Measurement Pixel does not support the app_installed and app_opened events. These events are supported in cloud mode, but not in web device mode.

Track event data

RudderStack maps the following event data fields in web device mode:

RudderStack property	OpenAI Ads field	Notes
`messageId` or configured deduplication key path	`event_id`	Sent in the Measurement Pixel event options. The configured path must resolve to a scalar value.
`properties.optOut` `properties.opt_out`	`opt_out`	Optional boolean value sent in the Measurement Pixel event options.
`properties.amount` `properties.value` `properties.revenue`	`amount`	Converted to the currency’s minor units when currency is available.
`properties.currency` Default currency setting	`currency`	Sent when amount is present.
`properties.plan_id` `properties.planId`	`plan_id`	Sent for `plan_enrollment` and custom event data shapes.
`properties.contents` `properties.products`	`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`
`quantity` `count`	`quantity`
`amount` `value` `price`	`amount`
`currency` `currency_code` `currencyCode`	`currency`

Page

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

A sample page call is shown below:

javascript

rudderanalytics.page();

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

Screen

The OpenAI Ads web device mode integration does not support the screen call. Send screen events in cloud mode instead.

OpenAI Ads Web Device Mode Integration

Add web device mode integration

Identify

Track

Track event data

Page

Screen

Questions? Let's figure it out together.