Google Pub/Sub (Cohort Sync)

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 and Behavioral Cohorts.
• 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:

{
  "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 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 for help with this step.

Google Pub/Sub setup

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.

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.