Amplitude integration

Developer assistance needed

You will need help from your development team to set up the integration. Share this guide with them.

Amplitude, a robust product analytics platform, empowers businesses to understand user behavior in real-time, track in-product interactions, and gain valuable insights into user engagement, retention, and revenue.

Integrating Amplitude with Pushwoosh allows you to personalize Pushwoosh campaigns with Amplitude data, trigger automated campaigns based on user actions, analyze performance for continuous improvement, and ultimately drive enhanced engagement, reduced churn, and increased revenue.

Integration overview

Integration type

Destination: Data is sent from Amplitude to Pushwoosh.

Prerequisites

To set up the Event Streaming and Cohort Sync integration from Amplitude to Pushwoosh, ensure the following prerequisites are met:

• You need an active Pushwoosh account.
• Generate an API Access Token in Pushwoosh to send data.
• Locate your Pushwoosh Application Code before configuring the integration.
• This integration is only available to Amplitude customers with paid plans.
• You must have a paid Pushwoosh plan to use this integration.

Glossary (mapping entity names if they are different)

Cohorts in Amplitude = Segments in Pushwoosh

Synchronized entities

• Events
• Tags
• Segments

How does the integration work?

The Amplitude Integration with Pushwoosh operates by syncing data between the two platforms to enhance user engagement and segmentation. Here is a detailed breakdown of how it works:

Data Transmission

• Events: Amplitude sends event data to Pushwoosh. Each event contains a user ID (external_id), an application code (app_id), the event name (event_name), a timestamp (created_at), and event properties (properties).

  • Pushwoosh takes the platform from properties.platform (iOS, Android, or Web). An event without it is recorded as an iOS event.
  • Pushwoosh takes the device ID from properties.device_id. Without it, the user ID is used as the device ID.
  • Property values of any type are accepted and stored as event attributes. Numbers and booleans are kept as their text, and empty (null) values are skipped.
  • A new event is created in Pushwoosh automatically on first receipt. Its attribute types are inferred from the values: date, integer, boolean, price, or string. When an existing event gets a new property, Pushwoosh adds it as an attribute automatically, up to 100 attributes per event. Such attributes are typed from the text only, as date, version, or string, so a numeric property added later becomes a string attribute.

• Tags: Pushwoosh receives user properties and saves them as tags on the user. Each request contains a user ID (external_id, required), an application code (app_id), and user properties (properties).

  • Missing tags are created automatically, with the type inferred from the value the same way as for event attributes.
  • Properties named like Pushwoosh default tags, such as Language, Country, or Timezone, are ignored.

• Segments: For each synced cohort, Pushwoosh creates a segment with the cohort name. Cohort membership is stored as a value of the CSV import list tag on the user, and users are matched by User ID. Users are added to or removed from the segment as Amplitude syncs the cohort.

Data Flow

• Events and Tags: Data is sent from Amplitude to Pushwoosh based on user interactions or attributes tracked in Amplitude. Events and tags are created or updated in Pushwoosh according to the configuration and mappings set up in Amplitude.

• Segments: Segments are created in Pushwoosh when Amplitude makes a request. Pushwoosh generates a unique identifier for each segment, which Amplitude uses to manipulate the segment by adding or removing users.

Requests

Requests are sent to specific endpoints in Pushwoosh to handle events, user attributes, and segment updates. Each request requires authentication and has specific headers and payload formats.

Use cases

Event tracking

Track user actions and interactions from Amplitude and send these events to Pushwoosh to trigger notifications or updates.

User tagging

Assign tags to users based on their behavior or attributes in Amplitude. These tags can be used in Pushwoosh for targeted messaging or segmentation.

Segment management

Create and manage user segments in Pushwoosh based on the data and segments configured in Amplitude. This helps in targeting specific groups of users with personalized messages.

Automated user management

Automatically add or remove users from segments based on their actions or attributes in Amplitude, ensuring up-to-date segmentation in Pushwoosh.

Setting up the integration

Cohort sync

Pushwoosh setup

1. In Pushwoosh, create or copy an API Access Token in Settings > API Access.
2. Copy the Application Code of the app you want to sync cohorts to.

Amplitude setup

To configure Amplitude for integration, follow these steps:

1. In your Amplitude Data, go to the Catalog and select Destinations.
2. Under the Cohort section, locate and click Pushwoosh.

3. Click Add another destination.

4. Provide a name and paste the API Access Token you copied from Pushwoosh.

5. Map the Amplitude User ID field to the Pushwoosh User ID field. Pushwoosh matches cohort members by User ID, so the Amplitude field you select must contain the same value that your app sets as the User ID in Pushwoosh. Amplitude’s setup page states that the field must contain an email address. If your app sets a different value as the Pushwoosh User ID, cohort members aren’t matched. In that case, set the user’s email as the User ID in the Pushwoosh SDK, or contact Pushwoosh support.
6. Save your settings when you are done.

Sending a cohort

To synchronize your first cohort, complete the following steps:

1. In Amplitude, open the cohort you wish to synchronize, then click on Sync.

2. Choose Pushwoosh and select the account you want to synchronize with. Then, click Next.

3. Decide on the synchronization cadence and save your configurations.

Event streaming

Pushwoosh setup

1. Create or copy an API Access Token in Settings > API Access.

2. Copy the Application Code of your app.

Amplitude setup

1. In Amplitude, go to Data Destinations and find Pushwoosh - Event Stream.

2. Enter a sync name and then click Create Sync.

3. Change the Status from Disabled to Enabled and paste your Pushwoosh API Access Token and Application Code.

4. From the left dropdown, select the Amplitude user property that corresponds to your Pushwoosh UserID.
5. (Optional) Enable the Create & Update users toggle if you want to send users and their properties in real-time whenever Amplitude creates or updates a user property.

6. Enable Send Events (“Events are sent to Pushwoosh”) if you want to stream events to Pushwoosh. This will automatically forward events to Pushwoosh as they are ingested in Amplitude. Events are not sent on a schedule or on demand using this integration.

8. Then, choose which events you want to send in the Select and Filter Events section. Only select the events you need in Pushwoosh; transformed events are not supported.
9. Once done, enable the destination and click Save.

How do you know that the integration is working?

To verify that the Amplitude and Pushwoosh integration is functioning correctly, you can use the following methods:

Monitor Pushwoosh dashboard

• Events and Tags: Check the Pushwoosh dashboard to see if the events and tags sent from Amplitude appear as expected. Look for recent activities or updates related to your events and tags.
• Segments: Verify that segments are being created, updated, or modified based on the data from Amplitude. Ensure that user counts and segment memberships reflect expected changes.

Check API responses

• Successful responses: Ensure that you receive 200 OK responses from the Pushwoosh API endpoints. Although there may not always be a response body, the 200 OK status indicates that the request was successfully received.
• Error responses: Review status codes other than 200 OK for clues if something is not working:
  • 400 Bad Request: the request body is not valid JSON, or the user ID is missing.
  • 401 Unauthorized: the API token or the application code is missing, invalid, or the token belongs to another account.
  • 503 Service Unavailable: Pushwoosh is temporarily unable to process the event. The request can be retried.
  • Other 5xx codes: an internal error while checking the API token, saving tags, creating a segment, or updating cohort membership. Retry the request later.
• Events that Pushwoosh rejects because of their content get 200 OK and are not processed, so a 200 OK alone doesn’t confirm that an event was recorded.

Log requests and responses

• Request logs: Maintain logs of outgoing requests from Amplitude and incoming responses from Pushwoosh. Check these logs to ensure that requests are formatted correctly and responses are as expected.
• Error logging: Implement error logging to capture any issues during data transfer or integration processes.

Test with sample data

• Send test Events/Tags: Create and send test events and tags from Amplitude to Pushwoosh. Verify that these test entries appear correctly in Pushwoosh and trigger expected behaviors.
• Simulate user actions: Perform actions in Amplitude that should trigger specific events or updates in Pushwoosh. Check if these actions result in the expected changes in Pushwoosh.

Use monitoring tools

• Integration monitoring: Utilize monitoring tools or services that can track the health and performance of the integration. These tools can alert you to issues or failures in real-time.
• Analytics and reporting: Use analytics features in both Amplitude and Pushwoosh to review data flow and integration performance.

Review integration documentation

• Configuration review: Double-check the integration configuration in both Amplitude and Pushwoosh to ensure all settings and mappings are correctly applied.
• Documentation updates: Stay updated with any changes or updates in the integration documentation that might affect functionality.

Contact support

If you encounter persistent issues or inconsistencies, reach out to the support teams of Amplitude or Pushwoosh for assistance. Provide them with details of the integration setup and any error logs for faster resolution.

Troubleshooting

Integration issues

• Event not appearing in Pushwoosh: Ensure the event is correctly mapped, and verify that the Pushwoosh application code and API token are properly configured.

• Tags not syncing: Confirm that the tags are formatted correctly and that all necessary authentication details are included in the request.

Segment problems

• Segment not created: Check that the request to create the segment is correctly formatted and that the Pushwoosh API token is valid.

• Users not added/removed: Verify that the user IDs are correctly specified and that the segment ID is valid. Ensure the request payload is properly formatted.

Response issues

• No response body: A 200 OK response has no body. It doesn’t confirm that an event was recorded, because events rejected for their content also get 200 OK (see Check API responses). Check the event in Pushwoosh as described in Monitor Pushwoosh dashboard.

FAQ

What should I do if I receive a 400 Bad Request error?

Pushwoosh returns 400 when the request body is not valid JSON or the user ID (external_id) is missing. Check that the user ID mapping in Amplitude points to a property that is filled for every user.

How can I verify if the integration is working?

Check the Pushwoosh dashboard for incoming events, tags, and segment updates. You can also monitor logs or responses from API endpoints for successful data transfers.

Can I customize the events or tags sent to Pushwoosh?

Yes, you can customize events and tags within the Amplitude configuration. Make sure that the data adheres to the expected Pushwoosh format.

How often is the data synced between Amplitude and Pushwoosh?

Data syncs in real-time or near-real-time based on requests made from Amplitude. Ensure your configuration supports the desired update frequency.

Where can I find more information or support for this integration?

Refer to the official documentation from Amplitude and Pushwoosh. For further assistance, contact the respective support teams.