Piano Analytics

Web Source code Package

Piano Analytics is an enterprise analytics and audience platform. The destination configures the official Piano pa SDK with your site id and collection domain, and forwards events via pa.sendEvent. With loadScript: true it also loads the SDK.

Where this fits

Piano is a web destination in the walkerOS flow:

Installation

npm install @walkeros/web-destination-piano

Integrated

import { startFlow } from '@walkeros/collector';
import { destinationPiano } from '@walkeros/web-destination-piano';

await startFlow({
  destinations: {
    piano: {
      code: destinationPiano,
      config: {
        loadScript: true,
        settings: {
          site: 123456789,
          collectDomain: 'https://example.pa-cd.com',
        },
      },
    },
  },
});

Bundled

Add to your flow.json destinations:

"destinations": {
  "piano": {
    "package": "@walkeros/web-destination-piano",
    "config": {
      "loadScript": true,
      "settings": {
        "site": 123456789,
        "collectDomain": "https://example.pa-cd.com"
      }
    }
  }
}

See bundled mode setup | CLI reference

Configuration

This destination uses the standard destination config wrapper (consent, data, env, id, ...). For the shared fields see destination configuration. Package-specific fields live under config.settings and are listed below.

Settings

Property	Type	Description	More
site*	number	Piano Analytics site id (numeric), from your collection settings
collectDomain*	string	Collection domain endpoint, like https://xxxxxxx.pa-cd.com
options	Record<string, any>	Additional Piano setConfigurations options merged on init

* Required fields

Mapping

This package does not define custom rule-level settings. For the standard rule fields (consent, condition, data, batch, name, policy) see mapping.

Examples

Custom event

A generic entity action fires a custom Piano event with mapped properties.

Event

{
  "name": "entity action",
  "data": {
    "string": "foo",
    "number": 1,
    "boolean": true,
    "array": [
      0,
      "text",
      false
    ]
  },
  "context": {
    "dev": [
      "test",
      1
    ]
  },
  "globals": {
    "lang": "elb"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [
    {
      "entity": "child",
      "data": {
        "is": "subordinated"
      }
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "7ed36be48eaf44d3",
  "trigger": "test",
  "entity": "entity",
  "action": "action",
  "timestamp": 1700000202,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}

Mapping

{
  "name": "click.action",
  "data": {
    "map": {
      "label": "data.string",
      "value": "data.number"
    }
  }
}

Out

pa.sendEvent("click.action", {
  "label": "foo",
  "value": 1
})

Initialization

Destination bootstrap configures Piano with the site id and collection domain.

Event

{
  "settings": {
    "site": 123456789,
    "collectDomain": "https://example.pa-cd.com"
  }
}

Out

pa.setConfigurations({
  "site": 123456789,
  "collectDomain": "https://example.pa-cd.com"
})

Page view

A page view fires a Piano page.display event with the page name and chapter.

Event

{
  "name": "page view",
  "data": {
    "domain": "www.example.com",
    "title": "walkerOS documentation",
    "referrer": "https://www.walkeros.io/",
    "search": "?foo=bar",
    "hash": "#hash",
    "id": "/docs/"
  },
  "context": {
    "dev": [
      "test",
      1
    ]
  },
  "globals": {
    "pagegroup": "docs"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [
    {
      "entity": "child",
      "data": {
        "is": "subordinated"
      }
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "a7ca8a89edf9a549",
  "trigger": "load",
  "entity": "page",
  "action": "view",
  "timestamp": 1700000200,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}

Mapping

{
  "name": "page.display",
  "data": {
    "map": {
      "page": "data.title",
      "page_chapter1": "globals.pagegroup"
    }
  }
}

Out

pa.sendEvent("page.display", {
  "page": "walkerOS documentation",
  "page_chapter1": "docs"
})

Purchase

A completed order fires a Piano transaction.confirmation event with the transaction id, revenue and currency.

Event

{
  "name": "order complete",
  "data": {
    "id": "0rd3r1d",
    "currency": "EUR",
    "shipping": 5.22,
    "taxes": 73.76,
    "total": 555
  },
  "context": {
    "shopping": [
      "complete",
      0
    ]
  },
  "globals": {
    "pagegroup": "shop"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [
    {
      "entity": "product",
      "data": {
        "id": "ers",
        "name": "Everyday Ruck Snack",
        "color": "black",
        "size": "l",
        "price": 420
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    },
    {
      "entity": "product",
      "data": {
        "id": "cc",
        "name": "Cool Cap",
        "size": "one size",
        "price": 42
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    },
    {
      "entity": "gift",
      "data": {
        "name": "Surprise"
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "f0459a803a14935a",
  "trigger": "load",
  "entity": "order",
  "action": "complete",
  "timestamp": 1700000201,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}

Mapping

{
  "name": "transaction.confirmation",
  "data": {
    "map": {
      "transaction_id": "data.id",
      "revenue": "data.total",
      "currency": "data.currency"
    }
  }
}

Out

pa.sendEvent("transaction.confirmation", {
  "transaction_id": "0rd3r1d",
  "revenue": 555,
  "currency": "EUR"
})

Loading the SDK

With loadScript: true, the destination adds the SDK script https://tag.aticdn.net/piano-analytics.js and configures pa with site, collectDomain and options once the script has loaded. If the script fails to load, it logs a warning. Until the SDK has loaded, the destination drops every event it receives and counts it as delivered. That includes the page view a browser source sends when the flow starts.

To keep the first events, load the Piano SDK on your page before walkerOS starts and leave loadScript unset. The destination then configures pa at init.

Event names

Each rule's name becomes the Piano event name and its data object the event properties, as in the examples above. Without a rule, the destination sends the walkerOS event name, like page view, with no properties.