Piano Analytics icon

Piano Analytics

Use the Piano Analytics API
Join our community

Actions6

Overview

This node integrates with the Piano Analytics Collection API to send event data directly from any platform. It is designed to post custom user interaction events or other tracking data to Piano Analytics for real-time collection and analysis.

Typical use cases include:

  • Sending user behavior events (e.g., clicks, page views) from web or mobile applications.
  • Tracking custom events with associated properties for detailed analytics.
  • Integrating event data pipelines where events are generated outside of standard web tracking setups.

For example, you can send an array of events describing user actions on a website, including event names and custom properties, which Piano Analytics will collect and process.

Properties

Name Meaning
User Agent The HTTP User-Agent string to identify the client sending the events.
Collection Domain The domain part of the URL where the events are sent (e.g., example.com).
Path The path appended to the domain forming the full endpoint URL for event collection.
Site ID Identifier of the site in Piano Analytics to which the events belong.
Visitor ID Unique identifier for the visitor generating the events.
Events Array JSON array of event objects to send. Each event includes a name and associated data properties.

The Events Array property expects JSON structured like this:

{
  "events": [
    {
      "name": "event.name",
      "data": {
        "property": "value",
        "property2": "value"
      }
    }
  ]
}

Output

The node outputs a JSON array where each element corresponds to the response from the Piano Analytics API for each input item processed.

  • If the API returns content, it is parsed from JSON and returned as the output.
  • If no content is returned (HTTP 204), the output contains an object indicating "Status Code": "204 No Content".

No binary data output is produced by this operation.

Dependencies

  • Requires an API key credential for authenticating requests to the Piano Analytics API.
  • The node makes HTTP POST requests to the constructed Collection API endpoint.
  • Proper configuration of the API credentials within n8n is necessary.

Troubleshooting

  • Missing Credentials Error: If the API key credential is not set or invalid, the node will throw an error indicating missing credentials.
  • Required Parameter Errors: The node validates required parameters such as Organization Code, Enrichment Id, Reconciliation Key (for enrichment operations), and Columns, Period, Site (for extract operations). Missing these will cause errors.
  • Invalid JSON in Events Array: The eventsArray must be valid JSON. Malformed JSON will cause parsing errors.
  • API Request Failures: Network issues or incorrect domain/path may result in failed requests. Check the Collection Domain and Path values.
  • Error Messages: Errors from the API or internal exceptions are wrapped and reported with messages prefixed by "Error calling Piano Analytics API:" followed by the original error message.

To resolve common issues:

  • Verify all required fields are filled correctly.
  • Ensure the JSON in the Events Array is well-formed.
  • Confirm that the API credentials are valid and have appropriate permissions.
  • Check network connectivity and correct endpoint URLs.

Links and References

Discussion