Configure campaigns for Amplitude

Amplitude is a self-service digital analytics platform to understand your users, drive conversions, and increase engagement, growth and revenue.

Beta

The Amplitude connector is in beta. Contact your Amperity representative to learn more.

A campaign sends an audience to Amplitude as a behavioral cohort, so product teams can run funnel, retention, and feature-adoption analyses against an Amperity-resolved audience inside Amplitude.

Note

This destination uses several of Amplitude’s REST APIs : the HTTP V2 and Batch Event Upload APIs for events, the Identify and Group Identify APIs for user and group properties, the Behavioral Cohorts API for audiences, and the User Privacy API for deletion requests.

Important

Set Write mode to cohort-push on a campaign destination. It defaults to user-properties, which writes user properties instead of cohort membership, and only cohort-push sends an audience. Leave Attribute updates only cleared — selecting it suppresses the audience the cohort is built from, and the run fails with a message naming that setting.

In cohort-push mode, one orchestration or campaign maintains one Amplitude behavioral cohort, named by the Cohort name setting. Amperity creates the cohort on the first run and updates the same cohort on later runs of that name.

Every cohort’s first run sends the full audience, in either Cohort sync mode, because Amplitude assigns the cohort’s identifier only on that first full send. From the second run onward, replace keeps re-sending the full audience and append sends only the members added and removed since the last run.

Important

Amplitude only recognizes identities it has already seen. An identity that has never been sent through user-properties or events mode is not matched into a cohort — Amplitude reports it as invalid, and Amperity reports those rows as failed. Send an audience’s identities as user properties or events before, or alongside, pushing them into a cohort.

If the cohort is deleted in Amplitude between runs, the next run creates a replacement cohort under the same name and continues from there. The replacement is a new cohort, so anything in Amplitude that referenced the deleted one — a chart, a saved analysis — needs to be pointed at the new cohort.

An audience that is empty on a given run is not sent: Amplitude rejects an empty membership, so the cohort keeps the membership it already had. This is reported as a warning in the run details rather than as a failure.

Note

The Amplitude region setting must match the region your Amplitude project is hosted in. Amperity sends to different Amplitude hosts for us and eu, and a mismatch sends every request to the wrong host, so the run fails.

Get details

Review the following details before configuring credentials for Amplitude and before configuring Amperity to send audiences to an Amplitude project.

	Credential settings Required Both credential fields are required. No call can be made without them. API Key Required. The API Key for the Amplitude project this destination writes into. Copy it from Settings > Projects > [your project] > General in Amplitude, where it appears alongside the Secret Key. Secret Key Required. The Secret Key for the same Amplitude project as the API Key. Amperity pairs the two keys to authenticate the Behavioral Cohorts and User Privacy APIs, which back the cohort-push and user-deletion write modes. Important Both keys are always required, even when the destination only uses a write mode that does not need the Secret Key. The two values must come from the same Amplitude project — a mismatched pair fails the connection test. Both values are on the same page in Amplitude: open Settings, select Projects, and select the project. On its General tab, select Manage next to API Key or Secret Key to view and copy each value.
	Required configuration settings Write mode Required Required for a campaign. Select cohort-push, which sends the campaign’s audience to Amplitude as one behavioral cohort. No other write mode sends an audience. Important Write mode defaults to user-properties. A campaign destination left at that default writes user properties instead of cohort membership, so set this explicitly. Identity column Required Required. The column in the query results that carries each row’s identity. This is always identity_value — your query must return a column with that exact name. What that value means depends on the write mode: the Amplitude user_id in user-properties and events modes, the group’s value in group-properties mode, the cohort member in cohort-push mode, or the identity to delete in user-deletion mode. Cohort identifier type Required Applies to cohort-push mode only, and is required for it. Whether the values in the identity column are Amplitude’s own assigned identifiers (amplitude_id) or the identifiers your own systems assign (user_id). Caution Amplitude looks up every value as the type you choose here. If the type is wrong, nothing matches — the rows are reported as failed and the cohort is left empty or unchanged. Confirm which identifier your query returns before the first run. Cohort owner email Required Applies to cohort-push mode only, and is required for it. The login email address of the Amplitude account that owns the cohort. Amplitude requires an owner on every cohort call. Use the email address of a real Amplitude user in the project the cohort belongs to. Amplitude app ID Required Applies to cohort-push mode only, and is required for it. The numeric Amplitude project ID that the cohort is created in. This is a separate value from the API Key and Secret Key and cannot be derived from them — copy it from the project’s settings page in Amplitude. Cohort name Required Applies to cohort-push mode only, and is required for it. The display name of the Amplitude behavioral cohort this orchestration maintains. Amperity also uses it to recognize the cohort across runs, so repeat runs of the same name update the same Amplitude cohort instead of creating another one. Changing the name starts a new cohort on the next run and leaves the old one in place, unchanged.
	Optional configuration settings Amplitude region The Amplitude data-residency region this destination connects to: us (the default) or eu. This selects the Amplitude hosts Amperity sends to, so it must match the region your Amplitude project is hosted in. A region that does not match the project’s own region sends every request to the wrong Amplitude host and the run fails. Cohort sync mode Applies to cohort-push mode only. How each run updates the cohort’s membership: replace (the default) sends the full current audience every run, overwriting the cohort’s membership. append sends only the members added and removed since the last run. A cohort’s first run always sends the full audience, in either mode, because Amplitude assigns the cohort’s identifier only on that first full send. append takes effect from the second run onward. Cohort published Applies to cohort-push mode only. Whether the cohort is discoverable by users in the Amplitude UI. Cleared by default, which keeps the cohort hidden. Select it when the product teams who use the cohort need to find it themselves in Amplitude.

Configure credentials

Configure credentials for Amplitude before adding a destination.

An individual with access to Amplitude should use SnapPass to securely share “API Key” and “Secret Key” details with the individual who configures Amperity.

To configure credentials for Amplitude

	From the Settings page, select the Credentials tab, and then click the Add credential button.
	In the Create credential dialog box, do the following: From the Plugin dropdown, select “Amplitude”. Assign the credential a name and description that ensures other users of Amperity can recognize when to use this destination.
	The settings that are available for a credential vary by credential type. For the “amplitude” credential type, configure settings, and then click Save. Required Both credential fields are required. API Key Required. The API Key for the Amplitude project this destination writes into. Copy it from Settings > Projects > [your project] > General in Amplitude, where it appears alongside the Secret Key. Secret Key Required. The Secret Key for the same Amplitude project as the API Key. Amperity pairs the two keys to authenticate the Behavioral Cohorts and User Privacy APIs, which back the cohort-push and user-deletion write modes. Important Both keys are always required, even when the destination only uses a write mode that does not need the Secret Key. The two values must come from the same Amplitude project — a mismatched pair fails the connection test. Both values are on the same page in Amplitude: open Settings, select Projects, and select the project. On its General tab, select Manage next to API Key or Secret Key to view and copy each value.

Add destination

Use a sandbox to configure a destination for Amplitude. Before promoting your changes, send a sample audience, and then verify the results in Amplitude. After verifying the end-to-end workflow, push the destination from the sandbox to production.

To add a destination for Amplitude

	Open the Destinations page, select the New destinations button, and then select Campaign. To configure a campaign for Amplitude, do one of the following: Click the row in which Amplitude is located. Destinations list alphabetically and you can scroll up and down the list. Search for Amplitude. Start typing “ampl”. The list filters to show only matching destinations. Select “Amplitude”.
	Select the credential for Amplitude from the Credential dropdown, and then click Continue. Tip Amperity validates the connection when the destination is saved. If the connection cannot be validated, an error is shown and the destination is not saved.
	In the “Destination settings” dialog box, assign the destination a name and description that ensures other users of Amperity can recognize when to use this destination. Configure business user access By default a destination is available to all users who have permission to view personally identifiable information (PII). Enable the Admin only checkbox to restrict access to only users assigned to the Datagrid Operator and Datagrid Administrator policies. Enable the PII setting checkbox to allow limited access to PII for this destination. Use the Restrict PII access policy option to prevent users from viewing data marked as PII anywhere in Amperity and from sending data to downstream workflows.
	Configure the following settings, and then click “Save”. Write mode (Required at campaign) Required for a campaign. Select cohort-push, which sends the campaign’s audience to Amplitude as one behavioral cohort. No other write mode sends an audience. Important Write mode defaults to user-properties. A campaign destination left at that default writes user properties instead of cohort membership, so set this explicitly. Identity column Required. The column in the query results that carries each row’s identity. This is always identity_value — your query must return a column with that exact name. What that value means depends on the write mode: the Amplitude user_id in user-properties and events modes, the group’s value in group-properties mode, the cohort member in cohort-push mode, or the identity to delete in user-deletion mode. Amplitude region The Amplitude data-residency region this destination connects to: us (the default) or eu. This selects the Amplitude hosts Amperity sends to, so it must match the region your Amplitude project is hosted in. A region that does not match the project’s own region sends every request to the wrong Amplitude host and the run fails. Cohort identifier type Applies to cohort-push mode only, and is required for it. Whether the values in the identity column are Amplitude’s own assigned identifiers (amplitude_id) or the identifiers your own systems assign (user_id). Caution Amplitude looks up every value as the type you choose here. If the type is wrong, nothing matches — the rows are reported as failed and the cohort is left empty or unchanged. Confirm which identifier your query returns before the first run. Cohort owner email Applies to cohort-push mode only, and is required for it. The login email address of the Amplitude account that owns the cohort. Amplitude requires an owner on every cohort call. Use the email address of a real Amplitude user in the project the cohort belongs to. Amplitude app ID Applies to cohort-push mode only, and is required for it. The numeric Amplitude project ID that the cohort is created in. This is a separate value from the API Key and Secret Key and cannot be derived from them — copy it from the project’s settings page in Amplitude. Cohort sync mode Applies to cohort-push mode only. How each run updates the cohort’s membership: replace (the default) sends the full current audience every run, overwriting the cohort’s membership. append sends only the members added and removed since the last run. A cohort’s first run always sends the full audience, in either mode, because Amplitude assigns the cohort’s identifier only on that first full send. append takes effect from the second run onward. Cohort published Applies to cohort-push mode only. Whether the cohort is discoverable by users in the Amplitude UI. Cleared by default, which keeps the cohort hidden. Select it when the product teams who use the cohort need to find it themselves in Amplitude. Cohort name (Required at campaign) Applies to cohort-push mode only, and is required for it. The display name of the Amplitude behavioral cohort this orchestration maintains. Amperity also uses it to recognize the cohort across runs, so repeat runs of the same name update the same Amplitude cohort instead of creating another one. Changing the name starts a new cohort on the next run and leaves the old one in place, unchanged. Campaign file settings Under Campaign settings select one of the following: Send audience list as separate files This option sends a standalone file for each treatment group sending an audience to Amplitude. Send audience lists as a single file This option consolidates all treatment groups into a single file before sending the audience to Amplitude.
	After configuring this destination users may send campaigns to Amplitude.
	Validate the audience with Amplitude by using a sample audience with a very small membership. For example: 10 or 100 members or the minimum audience size recommended by Amplitude. Send the sample audience to Amplitude and verify the sample audience is correct in Amplitude. Make adjustments if necessary. Only send full audiences after validation is complete.