Piano Analytics

Web Source code Package

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

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": "b803b5d26d858e9c",
  "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": "37199f37fc94ffab",
  "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": "9b8873900128b2be",
  "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"
})