# OpenAI Ads Cloud Mode Integration


{{< customreadfile "/includes/openai-ads-private-beta.md" >}}

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]({{< ref "/destinations/rudderstack-connection-modes.md#cloud-mode" >}}).

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

## Track

Use the [`track`]({{< ref "event-spec/standard-events/track.md" >}}) 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]({{< ref "destinations/streaming-destinations/openai-ads/setup-guide.md#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`]({{< ref "event-spec/standard-events/page.md" >}}) 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`]({{< ref "event-spec/standard-events/screen.md" >}}) 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` <br /> `properties.actionSource` <br /> Default action source setting | `action_source` | Optional. Supported values are `web`, `mobile_app`, `offline`, `physical_store`, `phone_call`, `email`, and `other`. |
| `properties.source_url` <br /> `properties.sourceUrl` <br /> `context.page.url` | `source_url` | Required when `action_source` is `web`. |
| `properties.oppref` | `oppref` | Optional OpenAI Ads reference value. |
| `properties.optOut` <br /> `properties.opt_out` | `opt_out` | Optional boolean value. |

RudderStack maps the following event data fields:

| RudderStack property | OpenAI Ads field | Notes |
| :----| :-----| :-----|
| `properties.amount` <br /> `properties.value` <br /> `properties.revenue` | `data.amount` | Converted to the currency's minor units when currency is available. |
| `properties.currency` <br /> Default currency setting | `data.currency` | Required when amount is present. |
| `properties.contents` <br /> `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` <br /> `content_id` <br /> `contentId` <br /> `item_id` <br /> `itemId` <br /> `product_id` <br /> `productId` <br /> `sku` | `id` |
| `name` <br /> `title` <br /> `product_name` <br /> `productName` | `name` |
| `content_type` <br /> `contentType` <br /> `type` <br /> `category` <br /> `product_category` | `content_type` |
| `group_id` <br /> `groupId` | `group_id` |
| `variant_dict` <br /> `variantDict` | `variant_dict` |
| `quantity` <br /> `count` | `quantity` |
| `amount` <br /> `value` <br /> `price` | `amount` |
| `currency` <br /> `currency_code` <br /> `currencyCode` | `currency` |

## User matching fields

RudderStack hashes the following user matching fields before sending them to OpenAI Ads:

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

RudderStack rejects apparent pre-hashed values passed into non-hashed fields. Use the non-hashed source fields listed above and let RudderStack normalize and hash them.

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`.