{% callout type="note" %}
To gain access, contact your Amplitude Client Success Manager.
{% /callout %}

Amplitude Data's Google Vertex AI integration streams your Amplitude event data to Google Cloud Vertex AI Search for Commerce.

## Considerations

- Amplitude posts event data to Vertex AI's `userEvents.write` endpoint and maps each Amplitude event to the required Vertex AI schema using a FreeMarker template.
- Confirm your mapping matches the [Google Cloud User Events schema](https://docs.cloud.google.com/retail/docs/reference/rest/v2/projects.locations.catalogs.userEvents#UserEvent) before you enable the destination.

## Set up the integration

### Prerequisites

Before you get started, create a Google IAM service account with appropriate access.

Amplitude needs four things from Vertex AI to set up the integration:

- **Google service account JSON**: Create a dedicated service account for the Amplitude Vertex AI integration. Refer to the [Google documentation](https://cloud.google.com/iam/docs/service-accounts) for help with this step.
- **GCP project ID**: The name of the GCP project where the retail catalog lives.
- **Retail location**: Use `global` unless you have a regional catalog.
- **Retail catalog ID**: Use `default_catalog` unless you've created additional catalogs.

### Google Vertex AI setup

After you enable the Vertex AI `userEvents.write` endpoint and create the service account, create a key for the service account. You need this key to complete Amplitude setup. Refer to the [Google documentation](https://cloud.google.com/iam/docs/creating-managing-service-account-keys) for help with this step.

### Amplitude setup

1. In Amplitude Data, go to *Catalog > Destinations*.
2. In the *Event Streaming* section, click **Google Vertex AI**.
3. Enter a sync name, then click **Create Sync**.
4. Click **Edit**, then upload your service account JSON.
5. Update **GCP project ID**, **Retail location**, and **Retail catalog ID** if necessary.
6. Customize the payload using an [Apache FreeMarker](https://freemarker.apache.org/) template. Refer to the [FreeMarker templating language](#freemarker-templating-language) section.
7. Use the **Send events** filter to select the events to send.
8. When finished, enable the destination and click **Save**.

## FreeMarker templating language

Amplitude uses [Apache FreeMarker](https://freemarker.apache.org/) templates to transform Amplitude events into JSON that matches the [Vertex AI User Event schema](https://docs.cloud.google.com/retail/docs/reference/rest/v2/projects.locations.catalogs.userEvents#UserEvent). The `input` variable refers to each event in Amplitude's [export format](/docs/apis/analytics/export).

For advanced FreeMarker patterns, including datetime formatting and optional fields, refer to the [Webhooks Streaming destination](/docs/data/destination-catalog/webhooks#freemarker-templating-language).

{% callout type="tip" title="More FreeMarker help" %}
Refer to the FreeMarker [guide to creating templates](https://freemarker.apache.org/docs/dgui.html) for more help.
{% /callout %}

### Example template

```text
{
      <#if input.user_id??>
      "visitorId" : "${input.user_id}",
      </#if>
      "eventType" : "${input.event_type}",
      "eventTime" : "${input.event_time}",
      "productDetails" : [{
            "product" : {
                  "id" : "${input.event_properties.product_id!}"
            }
      }]
}
```

Using this template sends the following JSON payload to the Vertex AI `userEvents.write` endpoint:

```json
{
  "visitorId": "some user id",
  "eventType": "detail-page-view",
  "eventTime": "2022-10-24T20:07:32.123Z",
  "productDetails": [
    {
      "product": {
        "id": "product-123"
      }
    }
  ]
}
```

Adjust field names and nested objects to match the event types and properties you send. Map Amplitude `event_properties` and `user_properties` to the Vertex AI fields your catalog requires.