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. You can also choose user properties that set the name of the Account a user belongs to and that are saved as traits on that Account.
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 Connectors 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.
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:
Optionally, choose which user properties set the Account's name and traits. These fields appear once Vitally has received data from Amplitude, because they list the user properties Vitally has received. Both fields list user properties, not group properties. This can take up to 15 minutes after the first data arrives, and you may need to refresh the page.
1. Under Which user trait represents the name for the Account the user belongs to?, select the user property that holds the Account's name. If you leave this blank, or a User has no value for it, the Account uses its ID as its name.
2. Under Select any other traits that should also be associated to the Account in Vitally, select any other user properties that should also be saved as traits on the Account, such as plan or tier.
3. Save your changes. Accounts that Amplitude has already created are updated with the new name and traits, using the data from their Users.

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.
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:
Optionally, choose which user properties set the Account's name and traits. These fields appear once Vitally has received data from Amplitude, because they list the user properties Vitally has received. This can take up to 15 minutes after the first data arrives, and you may need to refresh the page.
1. Under Which user trait represents the name for the Account the user belongs to?, select the user property that holds the Account's name. If you leave this blank, or a User has no value for it, the Account uses its ID as its name.
2. Under Select any other traits that should also be associated to the Account in Vitally, select any other user properties that should also be saved as traits on the Account, such as plan or tier.
3. Save your changes. Accounts that Amplitude has already created are updated with the new name and traits, using the data from their Users.

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

Q: Why don't I see the Account name and Account traits fields in my Amplitude settings?

A: These fields list the user properties Vitally has received from Amplitude, so they appear only after Amplitude has sent data. This can take up to 15 minutes after the first data arrives, and you may need to refresh the page.

Q: What happens if an Account trait mapped from Amplitude has the same name as a trait from another source?

A: Vitally keeps one trait per name on an Account, so both sources write to the same trait. The most recently received value is kept.

Q: If Users on the same Account have different values for a mapped user property, which value does the Account use?

A: The Account uses the most recently received value from its Users.