Using Transcend's GraphQL API for Consent Analytics

Transcend's consent manager tracks several analytics events for site visitors, including consent preference changes, site sessions, page views, tracking purpose stats and more. You can query Transcend's GraphQL API to get analytics data related to site performance as it relates to the consent manager.

On this page:

Use Transcend's GraphQL Playground at api.transcend.io/graphql (or if you're using our US-hosted infrastructure, api.us.transcend.io/graphql) to explore the schema and run queries directly. You can use the Docs reference in the playground to explore the consent analytics queries: airgapBundleAggregateAnalytics() and airgapBundleTimeseriesAnalytics().

The airgapBundleAggregateAnalytics() and airgapBundleTimeseriesAnalytics() queries take two arguments:

  • id: "airgap_budle_id"
  • input: {}, where you can specify additional inputs for querying aggregate analytics data for an airgap.js bundle, including the analytics event metric to query for, start/end dates and analytics dimensions.

Let's look at an example, where we want to query to see the number of users who opted-in or out of a consent purpose (ex: Analytics). You can use the structure of the following query to get analytics data using the CONSENT_CHANGED metric to understand how many users gave consent (or conversely revoked consent) for different privacy regimes. The CONSENT_CHANGED metric is recording the event where a user opts in or out of a consent purpose. The event is stored with additional metadata that is used for tracking events and querying the analytics data.

When using this sample query, replace the Bundle_ID and the start/end times. Note that start/end times are timestamps in epoch times.

query {
  airgapBundleAggregateAnalytics(id: "<BUNDLE_ID_GOES_HERE>", input: {
    metric: CONSENT_CHANGED,
    includeDimensions:[NEW_VALUE,REGIME,PURPOSE]
    start: <EPOCH_START_TIME>,
    end: <EPOCH_END_TIME>
  }) {
    items {
      measure
      dimensions {
        NEW_VALUE
        REGIME
        PURPOSE
      }
    }
  }
  airgapBundleTimeseriesAnalytics((id: "<BUNDLE_ID_GOES_HERE>",
  input: {
    metric: SIGNAL_DETECTED,
    start: <EPOCH_START_TIME>,
    end: <EPOCH_END_TIME>,
    binInterval: "1h" // or "1m" or "1d"
  }) {
    items {
      time
      metric
      measure
    }
  }
}

You can use this snippet in the console to convert common analytics reporting time frames to epoch time and copy/paste into your GraphQL Query.

var daysAgo = (days) =>
  Math.floor(
    new Date(Date.now() - days * 24 * 60 * 60 * 1000).getTime() / 1000
  );
var sevenDaysAgo = daysAgo(7);
var thirtyDaysAgo = daysAgo(30);
var now = new Date(Date.now()) / 1000;

Let's look at a sample query response to better understand what the data reporting on.

Sample Response

{
  "data": {
    "airgapBundleAggregateAnalytics": {
      "items": [
        {
          "measure": "11",
          "dimensions": {
            "NEW_VALUE": "true",
            "REGIME": "GDPR",
            "PURPOSE": "Functional"
          }
        },
        {
          "measure": "1364",
          "dimensions": {
            "NEW_VALUE": "true",
            "REGIME": "Unknown",
            "PURPOSE": "Advertising"
          }
        }
        // etc
      ]
    }
  }
}

Breaking down the response data:

  • This query is looking up the metric “CONSENT_CHANGE”. So whenever the user opts in or out we record the consent change event and store this event with some metadata.
  • “PURPOSE” is the relevant purpose that was opted in/out of.
  • “NEW_VALUE” is the consent value (true = opted in, false = opted out)
  • “REGIME” is the relevant regime for that user when we recorded this consent change. This is relevant because users may start out as opted out or in by default depending on the regime and your configuration. GDPR users are opted out by default. CPRA users can be opted out or in by default, depending on your bundle configuration.

With this information in mind, the following object can be interpreted as: 1364 user events were recorded for opting IN to the analytics tracking purpose. It's worth noting that because the regime is GDPR, this means that these users were opted OUT by default, by gave consent for Analytics tracking purposes.

{
  "measure": "1364",
  "dimensions": {
    "NEW_VALUE": "true",
    "REGIME": "Unknown",
    "PURPOSE": "Advertising"
  }
}