Amplitude Data's Google Pub/Sub Cohort integration lets you stream your cohort membership updates straight to a Pub/Sub topic.

## Considerations

- This integration is only available for customers on paid Amplitude plans.
- You must enable this integration for each Amplitude project you want to use it in.
- Before you set up this integration, review [Amplitude Activation](https://help.amplitude.com/hc/en-us/articles/360028552471-Amplitude-Engage) and [Behavioral Cohorts](https://help.amplitude.com/hc/en-us/articles/231881448).
- Amplitude sends cohort updates through all supported cadences (Daily, Hourly, Real Time).
- All existing Real Time Cohort Sync limits apply.

## Payload

The payload sent to Pub/Sub is a JSON object. Example:

```json
{
  "cohort_name": "Test Cohort",
  "cohort_id": "gs72ns",
  "in_cohort": true,
  "computed_time": "1685748245",
  "message_id": "some-message-id:54",
  "users": [{
    "user_id": "user1@amplitude.com"
    },
    {
      "user_id": "user2@amplitude.com"
    }]
}
```

- `cohort_name`: String. The name of the audience.
- `cohort_id`: String. The unique ID of the audience, which also appears in the URL when you view the audience in Amplitude.
- `in_cohort`: Boolean. Indicates whether this batch of users is entering or exiting an audience. Each message contains one state, not both.
- `compute_time`: String. The Epoch timestamp when Amplitude recomputes the audience. Kinesis streaming can't enforce order on incoming messages. Use this timestamp to restore order.
  - Amplitude sends this value as a string rather than a number because some languages and platforms interpret JSON numbers as floats and lose precision.
- `message_id`: String. The unique ID of each message.
- `users`: List. The users batch. Each user appears as a JSON object.
  - `user_id`: String. The ID of the user.

## Set up the integration

### Prerequisites

Before you get started, create a topic in Pub/Sub and a Google IAM service account.

Amplitude needs two things from Pub/Sub to set up the integration:

- **Pub/Sub topic name**: The name of the topic, not the full name in Google Cloud. Refer to the [Google Pub/Sub](https://cloud.google.com/pubsub/docs/admin) documentation for help with this step.
- **Google service account key**: Create a dedicated service account for the Amplitude Pub/Sub integration. Refer to the [Google documentation](https://cloud.google.com/iam/docs/service-accounts) for help with this step.

### Google Pub/Sub setup

After you create your topic and service role, add the service account as a principal for the topic you created. For more detailed instructions, refer to the [Google documentation](https://cloud.google.com/pubsub/docs/access-control?hl=en#console).

1. Open the topic.
2. In the *Permissions* tab, click **Add Principal**.
3. Add the service account's name.
4. Select **Pub/Sub Publisher** as the role.

Next, create a key for the service account. You need this 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, click **Catalog** and select the **Destinations** tab.
2. In the Cohort section, click **Google Pub/Sub**.
3. Click **Add another destination**.
4. Enter the Display Name for this destination. This name identifies the destination when you sync the cohort.
5. Enter the Pub/Sub topic ID.
6. Upload the service account key in `.json` format based on the setup above.
7. Save the destination.

Amplitude creates the destination for cohort syncs.

## Send a cohort

1. In Amplitude, open the cohort you want to export.
2. Click **Sync**, and choose **Google Pub/Sub**.
3. Select the destination you created.
4. Select the sync frequency you need.