On this page

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:

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

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.

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

Was this helpful?