Guide: Using Captivate with Databox (Custom API Integration)

Leverage Captivate's API within Databox using the Metric Builder for Custom API Integrations, to gain insights into your podcast's audience engagement and performance metrics.

IN THIS ARTICLE

• Overview
• Specification
• Usage
  • How to connect Captivate to Databox
  • How to visualize data from Captivate
  • Examples
• Observations

Overview

Captivate.fm is a podcast hosting platform designed to help creators manage and monetize their podcasts.

The Captivate integration allows you to visualize your podcast's analytics in your Databox account. The data is brought in as Custom Metrics, created using the Metric Builder. Find out more about using the Metric Builder for Custom API Integrations here.

Specification

The table below shows how the integration is implemented and provides additional helpful resources and information.

Usage

How to connect Captivate to Databox

Go to Data Manager > + New connection. Type Captivate in the search bar and click on the Connect button. Next, click on the green Connect now button.

This will open the Activate Captivate window, where you will be prompted to enter your User ID and API Key to activate the connection. API keys can be found in the API Key section under My Account in your Captivate account.

Once your credentials are verified by our system, a new prompt will appear, allowing you to choose the podcast for which you wish to visualize analytics data.

How to visualize data from Captivate

The integrations already comes with a number of prebuilt Custom Metrics, but it is possible to expand on that number by creating more metrics yourself. To do that, reference the API documentation for specifics on what parameters should be used.

1. Navigate to Metrics > Custom Metrics to access the Metric Builder.
2. Click the green + New Custom Metric button and select the Captivate podcast in Data Source drop-down list.
3. Find the relevant endpoint in the API documentation that can be used to return the data you need. The base URL is already predefined, you only need to input the missing part of the chosen endpoint's URL.
4. Add any necessary parameters. Parameters sometimes are required to specify the Date Range to pull data for, or include/ exclude data based on a criteria. They are defined as key-value pairs. For date parameters, click on the calendar icon to enable dynamic date options. Multiple parameters can be added by clicking on the + control.
5. Add the request body in JSON format, if doing a POST request.
6. Add any necessary headers. Databox will automatically add a header with the Bearer token to authenticate the request.
7. Once you have all necessary fields populated, click on the green Continue button. You will be directed to the Select value step.
8. In the Select value step, select a property in the response that includes the metric value you'd like to use for the metric. A metric value must always be numeric.
9. Once you have selected the value, click on the green Continue button.
10. The Segment by dimension step is optional. This step will be taken into account only when you are trying to create a dimensional metric.
    1. If you'd like to segment your metric by multiple dimensions, choose one to complete during this set up, then start over and select a different dimension until each dimensional metric is created.

    2. To skip this step, select None. 

11. The Select date step is optional as well. You can choose between:
    1. Use current time of storing data (Dynamic): select this option if you want to associate the values with the current time.
    2. Use a field from response (optional): select this option if there is a date associated with each value.
12. In the Preview & Customize step, you can see the JSONata expression that has been created based on the chosen options.
    

    1. Pro tip: You can customize the JSONata expression in the right-hand panel, if you need further customization. More information about JSONata can be found here

13. To continue, click on the Preview data button to apply the JSONata expression to the response received from the API. You should see a table with dates, values and dimensions (if selected).
14. After you have previewed your data and verified it is working as expected, click on the green Continue button to proceed to the last step of the metric setup.
15. In the Describe metric step, populate the following:
    1. Name your metric: a name for the metric.
    2. Data aggregation: this determines how the data is handled. It impacts the way data is grouped and displayed for longer Date Ranges. Learn more here.
    3. Favorable trend: this affects how comparison values (i.e. deltas) are calculated and displayed on our visualizations. Choose UP if higher values are more disabled, and DOWN otherwise.
16. Once you completed the Describe metric step, click the green Continue button to save the metric in your account.

Examples

Below is a list of suggested additional metrics that you can create from this integration.

Downloads by Country

Unfortunately the API only provides aggregated totals for the whole period, instead of granular (daily) breakdowns. Therefore, in order to obtain granular data that can be later on aggregated on our visualizations based on the Date Range selection, it is necessary to sync only one day of data at a time. For that, we set up the request as outlined below.

{
    "start": "{{-1d}}",
    "end": "{{0d}}",
    "interval": "1d",
    "timezone": "{timezone}",
    "countryCode": null,
    "types": ["byLocation"]
}

byLocation.byCountry.{
    "value": total,
    "date": $$.totalOverTime.timestamp,
    "dimension": country
}

Downloads by Episode

This metric is already available as a Custom Metric, however the API only provides the ID of the episode in the response. To see the episode name instead, you'll need to rename the IDs in the JSONata expression.

{
    "start": "{{fdy}}",
    "end": "{{0d}}",
    "interval": "1d",
    "timezone": "{timezone}",
    "countryCode": null,
    "types": ["byEpisode"]
}

(
  $episodes := [
    {
        "id_1": "name_1",
        "id_2": "name_2"
    }
  ];

  byEpisode.overTime.{
    "value": total,
    "date": timestamp,
    "dimension": $lookup($episodes, %.episodeId) ? $lookup($episodes, %.episodeId) : %.episodeId
  }
)

Observations

Here are a few points to keep in mind about this integration.

Connection: each connection can only pull data for a single podcast. If you would like to visualize data from multiple podcasts, repeat the connection process for each new podcast.

Historical Data: you will be limited to the data returned by the metrics over time. So, in order to visualize data for a specific period (e.g. Last Year), make sure to include that range whenever preparing the API request.