Contentsquare icon

Contentsquare

Use the Contentsquare API

Actions76

Overview

This node integrates with the Contentsquare API to retrieve detailed user behavior and performance metrics related to website zones, pages, sites, and other entities. Specifically, for the Metrics API resource and the Get Zone Exposure Time operation, it fetches the amount of time a particular zone (a defined area on a webpage or app screen) was exposed to users.

This is useful in scenarios where you want to analyze how long users are actually seeing or engaging with specific parts of your web page or app interface. For example, marketers or UX analysts can use this metric to understand user attention patterns on different UI elements, helping optimize layout or content placement.

Practical examples:

  • Measuring exposure time of a promotional banner zone to evaluate its visibility.
  • Analyzing exposure duration of call-to-action buttons to correlate with conversion rates.
  • Comparing exposure times across devices (desktop, mobile, tablet) to tailor responsive designs.

Properties

Name Meaning
Zone ID The unique identifier of the zone for which the exposure time metric is requested. This is required to specify the target zone.
Query Parameters A collection of optional filters and parameters to refine the query:
- Device: Filter by device type (all, desktop, mobile, tablet).
- End Date: End date of analysis range.
- Format: Format of the query.
- Frequency: Export frequency filter.
- From: Export format filter.
- Goal ID: For conversion metrics on non-ecommerce goals.
- IDs: Comma-separated list of segment IDs to filter.
- Limit: Max number of results (default 50).
- Metric Type: Either Quantile or Average.
- Order: Result order, Ascending or Descending.
- Page: Page number of results.
- Period: Granularity of results (daily or none).
- Project ID: Target project ID (required for account-level API keys).
- Quantile: Percentile value used if metric type is quantile (default 75).
- Scope, Segment IDs, Start Date, State, To: Additional filtering options.

Output

The output JSON contains the response from the Contentsquare Metrics API endpoint for zone exposure time. It typically includes data points such as:

  • The total or average time the specified zone was visible to users.
  • Breakdown by any applied filters like device type, date range, or segments.
  • Metadata about the query such as pagination info if applicable.

If the API returns no content, the node outputs a status code message indicating "204 No Content".

The node does not output binary data.

Dependencies

  • Requires an API key credential with valid Client ID, Client Secret, and optionally Project ID and Scope for authentication.
  • The node performs OAuth2 client credentials flow to obtain an access token before making API requests.
  • The base API endpoint URL is dynamically retrieved during authentication.
  • Network connectivity to https://api.contentsquare.com is required.

Troubleshooting

  • Missing Client ID or Client Secret: The node will throw an error if these credentials are not provided. Ensure that the API key credential is configured correctly.
  • Zone ID is required: For the Get Zone Exposure Time operation, the Zone ID must be specified; otherwise, an error is thrown.
  • Failed to retrieve access token or endpoint: Indicates issues with authentication credentials or network problems.
  • API errors: Any HTTP or API errors are caught and reported with the message prefixed by "Error calling Contentsquare API".
  • Empty or invalid responses: If the API returns empty or malformed data, the node attempts to parse it but may output raw text or a no content status.

To resolve common issues:

  • Verify all required input properties are set.
  • Check API credentials and permissions.
  • Confirm network access to the Contentsquare API.
  • Review API limits and quota restrictions.

Links and References

Discussion