Track Campaign Performance Using the Metrics APIs in Amazon Pinpoint

Note: This post was written by Siddhanth Deshpande, a Software Development Engineer on the AWS Digital User Engagement team.

Today, we added Campaign Metrics and Application Metrics APIs to Amazon Pinpoint. You can use these APIs to programmatically access many of the metrics that are currently shown on the Analytics pages of the Amazon Pinpoint console. You can use these new APIs to analyze Amazon Pinpoint metrics in the reporting tool of your choice. For example, you can use these APIs to build a live custom dashboard to display your weekly campaign results, or to perform in-depth analytics on delivery rates for your campaigns. In this post, we’ll look at how to use these APIs to query key performance indicators (KPIs), as well as how to parse the response and pass the data to another service or application for further analysis.

Sending your request

The following Java sample code describes how to make a request to the Amazon Pinpoint Application Metrics API.

GetApplicationDateRangeKpiRequest request = new GetApplicationDateRangeKpiRequest()
        .withApplicationId(<YOUR_PINPOINT_PROJECT_ID>)
        .withKpiName(<KPI_NAME>)
        .withStartTime(Date.from(Instant.parse(<START_TIMESTAMP>)))
        .withEndTime(Date.from(Instant.parse(<END_TIMESTAMP>)));

These semantics also apply to the Amazon Pinpoint Campaign Metrics API. You can find a full list of metrics that are supported by these APIs at https://docs.aws.amazon.com/pinpoint/latest/developerguide/analytics.html.

Parsing the response

When you send your query, Amazon Pinpoint returns a JSON response that contains the data that you requested. The API groups the results by date, campaign ID, or another relevant field, depending on the metric. Amazon Pinpoint supports both single value KPIs, such as the count of unique message deliveries (unique-deliveries) and grouped by KPIs, such as the rate of successful deliveries grouped by date (successful-delivery-rate-grouped-by-date) through the same API call. Depending on the KPI that you queried, the shape of the result can vary. All KPI result rows include the result values. However, grouped by KPI result row values include an additional field indicating the keys used to group the result values, whereas single value KPI result row values do not.

You can use the following Java code example to display the data that’s contained in the response:

GetApplicationDateRangeKpiResult result = amazonPinpoint.getApplicationDateRangeKpi(request);
List<ResultRow> rows = result
        .getApplicationDateRangeKpiResponse()
        .getKpiResult()
        .getRows();

// Understanding the result

rows.forEach(row -> {
    System.out.print(
            String.format(
                    "Found values: %s",
                    row.getValues().stream().map(value -> String.format(
                            "Name:%s,Type:%s,Value:%s",
                            value.getKey(),
                            value.getType(),
                            value.getValue()
                    )).collect(Collectors.joining(";"))
            )
    );
    if (row.getGroupedBys() != null) {
        System.out.println(
                String.format(
                        " for keys: %s.",
                        row.getGroupedBys().stream().map(groupedBy -> String.format(
                                "Name:%s,Type:%s,Value:%s",
                                groupedBy.getKey(),
                                groupedBy.getType(),
                                groupedBy.getValue()
                        )).collect(Collectors.joining(";"))
                )
        );
    } else {
        System.out.println(".");
    }
});

For example, for the unique-deliveries KPI, you see a result that resembles the following example:

Found values: Name:UniqueDeliveries,Type:Double,Value:30.0.

For the successful-delivery-rate-grouped-by-campaign-activity KPI, you see a result that resembles the following example:

Found values: Name:SuccessfulDeliveryRate,Type:Double,Value:1.0 for keys: Name:CampaignActivityId,Type:String,Value:DATA_API_CAMPAIGN_ACTIVITY_ID_1.
Found values: Name:SuccessfulDeliveryRate,Type:Double,Value:1.0 for keys: Name:CampaignActivityId,Type:String,Value:DATA_API_CAMPAIGN_ACTIVITY_ID_2.

For the successful-delivery-rate-grouped-by-date KPI, you see a result that resembles the following example:

Found values: Name:SuccessfulDeliveryRate,Type:Double,Value:1.0 for keys: Name:Date,Type:String,Value:2019-01-01.
Found values: Name:SuccessfulDeliveryRate,Type:Double,Value:1.0 for keys: Name:Date,Type:String,Value:2019-01-02.
Found values: Name:SuccessfulDeliveryRate,Type:Double,Value:1.0 for keys: Name:Date,Type:String,Value:2019-01-03.

You can also define parsing logic that’s specific to the kind of KPI you are querying. For example, from the first of the preceding examples, we know that the unique-deliveries KPI returns a single value without any grouped by fields. You can then reduce the amount of logic that’s required to parse the result. You can use the following code example to parse the unique-deliveries KPI data:

if(!rows.isEmpty()) {
    ResultRowValue value = rows.get(0).getValues().get(0);
    System.out.print(
            String.format(
                    "Found value: Name:%s,Type:%s,Value:%s", 
                    value.getKey(),
                    value.getType(),
                    value.getValue()
            )
    );
}

Conclusion

Using these APIs enables you to monitor, assess, and share the performance of your campaigns without having to analyze raw event data. They also let you analyze metrics without having to sign in to the Amazon Pinpoint console. Sharing these metrics can help you and your team better understand your customers, and can help you find exciting new ways to use Amazon Pinpoint to engage with your customers.