Amplitude Data

Publishing your tracking plan to Amplitude Data


Introduction

The integration to Amplitude Data (opens in a new tab) allows for your Tracking Plan to be published into Amplitude Data whenever a branch has been merged. You can also manually trigger a publish by clicking the "Publish to Amplitude Data" button on the integration screen or download a CSV file on the Amplitude Data format, which you can manually import into Amplitude Data. The events to be published can be filtered by Sources, Destinations and Tags.

Configure the Amplitude Data integration

To enable the direct integration with Amplitude Data, you need to configure it with the following parameters from Amplitude. They can be found from the project settings in Amplitude. From the left sidebar in your Amplitude workspace click: Settings > Projects > [Your Project Name]. The URL should look like this: https://analytics.amplitude.com/{org-name}/settings/projects/{project-id}/general.

• Amplitude API Key
• Amplitude Secret Key
• EU Data Residency: Turn this on if you opted to store your data in Europe when you created your Amplitude project

Publishing to Amplitude Data

To publish your Avo tracking plan to Amplitude Data, click the "Publish to Amplitude Data" button in the integration interface, or enable Auto Publishing to publish the events included in the publishing integration whenever a branch has been merged.

What Is Included In The Publish to Amplitude Data?

On publish, Avo will merge your Avo tracking plan with any existing events and user properties in Amplitude Data. Any changes made to an event or a user property in Amplitude Data between Avo publish will be overridden on next Avo publish.

Avo will not impact any events or properties that are not defined in Avo, or events that have not been added to the Amplitude Data integration in Avo. Avo will publish all the user properties defined in your tracking plan to Amplitude. Avo will not impact any custom events or custom user properties defined in Amplitude Data and not defined in Avo.

Here's how events, event properties properties, categories and user properties are mapped from Avo to Amplitude Data:

Event

• Event type: The event name as defined in Avo. If name mapping is applied to the event for an Amplitude destination, the name defined by the name mapping is used here.
• Category: Amplitude Data only supports one category per event, so the first category attached to the event in Avo is used here
• Description: This is the description as provided in Avo and list of triggers defined in Avo for each source (including any attached screenshots)

Event Property

• Event property: The property name as defined in Avo. If name mapping is applied to the property for an Amplitude destination or all destinations, the name defined by the name mapping is used here.
• Event type: The name of the event this property is attached to. If the property is attached to multiple events in Avo, multiple properties will be created in Amplitude Data because Amplitude Data does not support reusing properties across multiple events with a global namespace.
• Type: The property type in Avo mapped to one of Amplitude Data's supported property types: string, number, boolean, enum or any
• Is array: true if the "list" checkbox is checked on the property in Avo
• Is required: true if the property is marked as "Always sent" in Avo
• Description: The property description as defined in Avo
• Enum values: If the property is of type string, and the "property matches..." rule is applied in Avo, the allowed values are provided here

Category

• Name: The name of the category as defined in Avo. If the category already exists in Amplitude Data, we reuse that one.

User Property

• User Property: The property name as defined in Avo. If name mapping is applied to the property for an Amplitude destination or all destinations, the name defined by the name mapping is used here.
• Description: The property description as defined in Avo
• Type: The property type in Avo mapped to one of Amplitude Data's supported property types: string, number, boolean, enum or any
• Enum values: If the property is of type string, and the "property matches..." rule is applied in Avo, the allowed values are provided here
• Is array: true if the "list" checkbox is checked on the property in Avo

Amplitude Data Publishing Warnings

• 409 Conflict: Some events or properties that are in your Amplitude Data Schema are not recognized by the Amplitude Data API, for example events that have been merged into other events in Amplitude Data or events/properties that are blocked. Events and properties that end up returning 409 error in Amplitude are likely not active. If you'd like to get rid of this warning please double check them and remove them from your Avo tracking plan if they are not active anymore.

Amplitude Data Publishing Errors

The following errors might occur when publishing your tracking to Amplitude Data. When publishing errors occur the error message in the Avo UI will contain which items could not be updated along with the error codes.

• 404 Not Found: This error can be thrown in few scenarios:

  • We tried to update an event or property that doesn't exist in your Amplitude Data Schema
  • If this error only occurs for events and properties Amplitude hasn't seen yet, it might indicate that the schema in Amplitude Data hasn't been initialized, or that you don't have access to the "Plan data" functionality in Amplitude Data
  • If this error occurs for all of the events you are attempting to publish it might indicate that your Amplitude Data Schema has not been initialized. Learn more about initializing your Amplitude Data Schema in the Amplitude Data docs (opens in a new tab). After you Amplitude Data Schema is initialized usually the API continues to return occasional 404 errors for a few more hours. If your Amplitude Data Schema has been initialized more than 6 hours ago and the error persists, please contact support.

• 408 Timeout: The publishing operation took too long. This can happen when publishing large tracking plans for the first time. Click publish again to resume the publish, it will continue from where it left off.

• 409 Conflict: We tried to update an item that doesn't exist in your Amplitude Data Schema. We noticed that this error may happen if the entity has a non-default state in your Amplitude Data schema, i.e. it is marked as "Unexpected" or "Blocked". Try setting the state to "Expected" in Amplitude Data and unblock erroring entities and publish again. If that does not help this might be caused by an internal error. Please reach out to support so we can help you resolve the issue.

• 429 Too Many Requests: We've exceeded the number of Amplitude Data requests we can make per hour for the provided API credentials or there are too many concurrent requests to the Amplitude Data API with given credentials. Please wait before trying to publish again and make sure that you are not running multiple publishing at the same time for the same credentials. You can learn more about Amplitude Data request limits in the Amplitude Data docs (opens in a new tab).

• Other error codes: Please contact us if you are experiencing other types of errors.