Amplitude

Amplitude integration guide

Amplitude is a digital optimization system with real-time data management, product and user analytics.

Amplitude lets you combine analytics from different sources so that you can act on the data and improve your product and services.

Example Analytics from [Amplitude](https://developers.amplitude.com/docs/how-amplitude-works)Example Analytics from [Amplitude](https://developers.amplitude.com/docs/how-amplitude-works)

Example Analytics from Amplitude

In Clarify we use Amplitude for user statistics and to optimize the product experience of our users.

This guide will show you how to visualize data from an Amplitude Chart in Clarify.

Amplitude data available in Clarify!Amplitude data available in Clarify!

Amplitude data available in Clarify!

👍

If you are not already using Amplitude

Check out Amplitude Pricing. They offer a free starter plan and a Startup Program.

Getting started

Before we get started, we assume that you have an Amplitude account and have started to collect events.

1. Create an Amplitude chart

In your Amplitude workspace, create a new Event Segmentation Chart. When creating the chart select some of the events you want to send to Clarify. It might look similar to the screenshot below.

Example chart in AmplitudeExample chart in Amplitude

Example chart in Amplitude

2. Find Amplitude chart ID

You can find the chart ID in the URL if you navigate to the chart you just created in Amplitude.

You'll find the chart ID in the latter part of the URL.
https://analytics.amplitude.com/YOURORG/chart/**CHARTID**

Note down the ID since we need it later in the guide.

3. Authentication

You authenticate via basic authentication with the project's credentials API_Key and Secret_Key. For instructions on how to find these keys, refer here.

4. Node-RED setup

If you are new to Node-RED or haven't checked out our Node-RED guides yet, we recommend that you check out Introduction to Node-RED before continuing.

5. Request setup

In Node-RED drag an Inject, "http request" & Debug node to your flow and connect them.

  • Double-click on the Debug node and set the output setting to complete msg object
  • Double-click on the "http request" node and name it Amplitude.

Your flow should now look similar to the screenshot below.

Connected Inject, "http request" and Debug nodes in Node-REDConnected Inject, "http request" and Debug nodes in Node-RED

Connected Inject, "http request" and Debug nodes in Node-RED

Now, double-click on the Amplitude node and configure its properties.

  • Method: GET
  • URL: https://amplitude.com/api/3/chart/**CHARTID**/query
  • Payload: ignore
  • Authentication: Select Use Authentication and basic authentication. Username should be the API_Key and Password is the Secret_Key you retrieved earlier in the guide.
  • Finally set Return to a parsed JSON Object.
"http request" node with Amplitude API configuration"http request" node with Amplitude API configuration

"http request" node with Amplitude API configuration

When you have stored the Amplitude node configuration, you can try to trigger your flow by clicking at the blue button in front of the Inject node and look at the response in the Debug console.

Click the blue button to trigger the flowClick the blue button to trigger the flow

Click the blue button to trigger the flow

Your response might look similar to the JSON below (we have removed some data to make it easier to read).

{
    "_msgid": "42d4446f.d2175c",
    "payload": {
        "data": {
            "series": [
                [
                    {
                        "setId": "",
                        "value": 3
                    },...
                ],
                [
                    {
                        "setId": "",
                        "value": 12
                    },...
                ],
                [
                    {
                        "setId": "",
                        "value": 1
                    },...
                ]
            ],
            "seriesLabels": [
                0,
                0,
                0
            ],
            "seriesIntervals": {},
            "xValues": [
                "2021-04-23",
                "2021-04-24",
                "2021-04-25",
                "2021-04-26",
                "2021-04-27",
                "2021-04-28",
                "2021-04-29",
                "2021-04-30"
            ]
        }
    },
    "topic": "",
    "statusCode": 200
}

We can find our chart data in payload.data.series and the timestamps in payload.data.xValues.
payload.data.series is an array of arrays of the event data in which the first array is the first event in your chart. So in the response above they are in the order Event 1, Event 2, and Event 3.

6. Prepare data

Now we are going to prepare the data we receive from the API before we send it to Clarify.

Drag a Function node between the Amplitude and Debug node as seen in the screenshot below.
Double-click on the new Function node and rename it to Prepare data.

Node-RED flow with new Prepare data nodeNode-RED flow with new Prepare data node

Node-RED flow with new Prepare data node

When you are ready, double-click the Prepare data node and use a code similar to the one below.
Tip: Rename the events in the code to match your own. (Make sure to avoid using IDs with special characters, whitespace, etc).

delete msg.headers;
delete msg.responseUrl;
delete msg.responseCookies;
delete msg.redirectList;

if (msg.statusCode == 200) {
    const DateTime = global.get('luxon').DateTime;
    
    let records = msg.payload.data.series;
    let dateRecords = msg.payload.data.xValues;
    
    const events = ["Event1","Event2","Event3"];
    
    events.forEach((event, index)=> {
        let dates = [];
        let values = [];
        
        if (records[index].length > 0) {
            records[index].forEach((item, nr)=> {
                dates.push(DateTime.fromISO(dateRecords[nr]));
                values.push(parseInt(item.value));
            });
        }
        msg.topic = "amplitude-" + event.toLowerCase();
        msg.signal = {
            name: "Amplitude " + event,
          labels: {
            "data-source": ["Amplitude"],
          }
        }
        msg.payload = {
          "times": dates,
          "values": values,
        }
        node.send(msg);
    }); 
}

return null;

In the code above we loop through the response data for each of the events and creates arrays of timestamps and data for each of the events before we send that as a message object.

We use the NPM package Luxon in the code above to work with date formats. You'll need to install this package or use a different package to handle dates. You can also check out the Node-RED guide.

Send data to Clarify

In this step, we'll send the actual data to Clarify. As a preparation, you need to follow the guides Installing the Clarify nodes and Using the Clarify Insert node to make sure your workflow is able to correctly send data to Clarify.

When you have installed the Clarify nodes and setup credentials you can connect the Prepare data node to the Clarify node. We also recommend that you connect two Debug nodes to the Clarify node. One for Errors and the other for other debug messages.

Complete flow in Node-RED which sends data to ClarifyComplete flow in Node-RED which sends data to Clarify

Complete flow in Node-RED which sends data to Clarify

To send the result to Clarify you can trigger the Inject node manually or set it up to trigger automatically as described below. We recommend you trigger it manually, to begin with, to verify that everything works as expected.

📘

Automatically trigger the flow

The Inject node supports automatic triggering at certain intervalls. You can achieve this by double-clicking on the Inject node and configuring the Repeat setting. For example by setting "repeat interval" with "1 hour" the workflow above will trigger and update data every hour.

6. Visualize data in Clarify

When our workflow has run we now have 3 new signals (or depending on the number of events in your chart) in Clarify which contains the data we received from the API.

To visualize the data we need to publish the signals as Items and create a new timeline.

If you follow this guide, you'll have Items similar to the ones below with fresh data.

Clarify with Amplitude data ItemsClarify with Amplitude data Items

Clarify with Amplitude data Items

Drag the Amplitude Items to the timeline and personalize the timeline with labels and colors that suit you and your company.

More data

Amplitude supports more methods of retrieving data. Check out their API Reference for inspiration.

Example
You can use the User Endpoint in the Amplitude API to create timelines in Clarify with your New and Active users.

Congratulations

You have Amplitude analytics data available in Clarify! Invite the rest of your team members to Clarify and create timelines, comment on data and collaborate as fresh new analytics data appear in Clarify.


Did this page help you?