Amplitude Overview

Vitally's Amplitude integration can be used to sync the following Amplitude data into Vitally:

Users - Vitally imports your Amplitude user profiles into Vitally as users. The entire user object, including all your Amplitude traits, will be attached to your Vitally user profiles
Tracks - Vitally imports your Amplitude tracks into Vitally as product events. The entire track object, including any event properties, will be imported.

Enabling the Amplitude integration

To begin syncing Amplitude data with Vitally, first enable the integration and follow the steps below. You'll need access to both your Amplitude account and the Vitally integration page:

In Vitally, navigate to Settings (⚙️) by selecting your Account Logo on the top left and under Operations select Integrations. Then select Amplitude (or via Quick Jump Mac: ⌘ + j Windows: Alt + j) to enable.
Configure the account and organization fields using one of the options below:

If using Group Types

Select the Use Amplitude's "Group Type" field radio button.
Input the Amplitude Group Type that represents the Account relationship
1. To find your available Group Types: In Amplitude, navigate to Users & Sessions > Accounts > all available groups can be seen in the All groups dropdown. In the below example we're defining the Playlists group as our Account Group Type
2. Now back in Vitally's Amplitude configuration page you can define the Customer Group Type. Continuing to use the above example, we've input "Playlists"
If applicable, configure Organization Group Type using the same process as step 2 (Please note Organization Group Type should be different than your Customer Group Type).
Input the optional user properties that define the user's name & email.
1. If you do not want to sync Amplitude users or user tracks, skip to step 5. If you want Amplitude users and user-level tracks to sync Vitally, continue below!
  1. To find your User name & email fields, navigate to your Amplitude, then navigate to Users & Sessions > User Look-Up > locate a user > under User Properties, find the desired fields. In the below example, the customers name and the customers email are the field names for name & email, respectively
  2. Back in Vitally's Amplitude configuration page, you'll define the user's name & email. Using the above example, we've input "the customers name" and "the customers email" as these fields:
Save your changes.
Navigate to Amplitude to configure a Webhook destination for Events & User Properties under Data > Catalog > Destinations > Webhook Events/User Properties)
1. Be sure to select the Webhook destination for Events & User Properties - Vitally does not currently support Cohorts
2. Provide a meaningful name for your Webhook destination. We've used Vitally Integration in our example:
In Vitally, go back to Integrations > Amplitude and find your API URL and API KEY. Then in your Webhook configuration in Amplitude:
1. Insert your API URL into the Webhook URL field.
2. Insert your API KEY as the header Authorization.
3. Ensure that Send Events is enabled and choose Send Amplitude's default payload.
4. Select the specific events you wish to import into Vitally.
5. Enable Send Users and choose Send Amplitude's default payload.
Finally, Trigger a few events from Amplitude and head back over to Vitally to wait for the page to show we've successfully received your webhooks! You should see a confirmation pop-up like below:

If using a User Property

Select the Use a custom user property radio button.
Input the Amplitude User Property that represents the Account relationship
1. To find your available User Properties: In Amplitude, navigate to Data > Properties > Users.
2. Now back in Vitally's Amplitude configuration page you can define the Account User Property.
If applicable, configure Organization User Property using the same process as step 2 (Please note Organization User Property should be different than your Account User Property).
Input the optional user properties that define the user's name & email.
1. If you do not want to sync Amplitude users or user tracks, skip to step 5. If you want Amplitude users and user-level tracks to sync Vitally, continue below!
  1. To find your User name & email fields, navigate to your Amplitude, then navigate to Users & Sessions > User Look-Up > locate a user > under User Properties, find the desired fields. In the below example, the customers name and the customers email are the field names for name & email, respectively
  2. Back in Vitally's Amplitude configuration page, you'll define the user's name & email. Using the above example, we've input "the customers name" and "the customers email" as these fields:
Save your changes.
Navigate to Amplitude to configure a Webhook destination for Events & User Properties under Data > Catalog > Destinations > Webhook Events/User Properties)
1. Be sure to select the Webhook destination for Events & User Properties - Vitally does not currently support Cohorts
2. Provide a meaningful name for your Webhook destination. We've used Vitally Integration in our example:
Go back to Integrations > Amplitude in Vitally and find your API URL and API KEY. Then in your Webhook configuration in Amplitude:
1. Insert your API URL into the Webhook URL field.
2. Insert your API KEY as the header Authorization.
3. Ensure that Send Events is enabled and choose Send Amplitude's default payload.
4. Select the specific events you wish to import into Vitally.
5. Enable Send Users and choose Send Amplitude's default payload.
Finally, Trigger a few events from Amplitude and head back over to Vitally to wait for the page to show we've successfully received your webhooks! You should see a confirmation pop-up like below:

Test connection

To test the connection you'll follow 5 steps:

Copy one of these request payloads and replace the values with anything you want
On the Amplitude settings page, click “Test connection”
On the “Sample Event Payload” section, paste the request payload of the step 1. Click on “Send Test Event”. After this, you should see a success message
Check if the data introduced on Vitally through this event is correct. To do this, select the "Return to My Account” button
Search for the account you just created. Click on it, and you’ll see the customer along with its associated user

Expand each step for more details and screenshots on testing the Amplitude connection:

1. Copy one of these request payloads and replace the relevant keys

Payload (groups)

Use these to test if using the Group Type to identify user accounts/orgs. The username and email information are always taken from user_properties.

// Identify event payload example 1
{
  "user_id": "Bill Shankly",
  "event_type": "Test event",
  "event_time": "2024-06-10 09:38:11",
  "data_type": "identify",
  "amplitude_id": "liverpoolFC",
  "groups": {
	  "<your-account-group-type>": "accountExternalId1",
	  "<your-organization-group-type>": "organizationExternalId1",
  },
  "user_properties": {
    "<your-user-name-path>": "Bill Shankly",
    "<your-user-email-path>": "bshankly@liverpool.com",
    "path": "Reebok",
    "accountGroupTypeAsUserProperty": "accountExternalId1"
  }
}

// Event example
{
  "user_id": "Mikel Arteta",
  "event_type": "Test event",
  "event_time": "2024-06-11 19:38:11",
  "data_type": "event",
  "amplitude_id": "arsenalFC",
  "groups": {
	  "accountGroupType": "accountExternalId2",
	  "organizationGroupType": "organizationExternalId2",
  },
  "user_properties": {
    "username": "MikelArteta",
    "email": "MikelArteta@arsenal.com",
    "path": "Puma",
    "accountGroupTypeAsUserProperty": "accountExternalId2"
  }
}

Payload (user_properties)

Use these if using a User Property to identify user accounts/orgs. In these examples, the configuration of the Customer Integration is set to take data from the key user_properties .

// Identify event payload example 1
{
  "user_id": "Bill Shankly",
  "event_type": "Test event",
  "event_time": "2024-06-10 09:38:11",
  "data_type": "identify",
  "amplitude_id": "liverpoolFC",
  "user_properties": {
    "<your-user-name-path>": "Bill Shankly",
    "<your-user-email-path>": "bshankly@liverpool.com",
    "<your-account-id-path>": "12345",
    "<your-organization-id-path>": "67890"
  }
}

// Even example
{
  "user_id": "Mikel Arteta",
  "event_type": "Test event",
  "event_time": "2024-06-11 19:38:11",
  "data_type": "event",
  "amplitude_id": "arsenalFC",
  "user_properties": {
    "username": "MikelArteta",
    "email": "MikelArteta@arsenal.com",
    "path": "Puma",
  }
}

2. On the Amplitude settings page, click “Test connection”

On the Amplitude settings page, click “Test connection”.

3. On the “Sample Event Payload” section, paste the request payload of the step 1. Click on “Send Test Event”. After this, you should see a success message

On the “Sample Event Payload” section, paste the request payload of the step 1. Click on “Send Test Event”. After this, you should see a success message like the image:

🚨 Sometimes the request may take longer than usual. You may have to wait a while to get results in Vitally.

4. Check if the data introduced on Vitally through this event is correct. To do this, select the "Return to My Account” button

Check if the data introduced on Vitally through this event is correct. To do this, select the "Return to My Account” button.

5. Search for the account you just created. Click on it, and you’ll see the customer along with its associated user

Search for the account you just created. Click on it, and you’ll see the customer along with its associated user.

If you have reached this point, congratulations! You have performed a successful data synchronization 🎉

Ignoring Events

In many cases it is not feasible to manually add each specific event type you want sent to Vitally. For this reason, you may find yourself importing all events and end up with a lot of non-relevant data in Vitally. To solve for this you will want to "ignore" any events you don't want to track in Vitally.

There are two benefits to "Ignoring" an event:

Keeps your event list cleaner in the UI as there will be fewer data to sift through.
This enables us to process your data as quickly as possible as we are not processing data that is not relevant to you.

To update an Event Status go to: Settings > Events > Status column

FAQs

Q: Is Amplitude bi-directional?

A: Amplitude is not bi-directional.

Q: Is it possible to sync only Account-level tracks from Amplitude to Vitally?

A: Yes. To sync Account-level tracks only, leave the User name and User email fields blank in Vitally.

Q: Does Amplitude support a historical sync?
A: No. Amplitude's Webhooks will only start sending data once they are configured.

Q: Can Amplitude be update only?

A: Yes, please reach out to Support@vitally.io