> Part of the walkerOS documentation. Project overview and full index: <https://www.walkeros.io/llms.txt>

# Piwik PRO

<!-- -->

[Web](#)[ ](https://github.com/elbwalker/walkerOS/tree/main/packages/web/destinations/piwikpro)

<!-- -->

[Source code](https://github.com/elbwalker/walkerOS/tree/main/packages/web/destinations/piwikpro)[ ](https://www.npmjs.com/package/@walkeros/web-destination-piwikpro)

<!-- -->

[Package](https://www.npmjs.com/package/@walkeros/web-destination-piwikpro)

[Piwik PRO](https://piwik.pro/) is a European, privacy-focused web analytics and marketing platform. The destination sends events to Piwik PRO via the `_paq` command queue, loading the tracking container script and forwarding page views, custom events, and ecommerce calls.

<!-- -->

Where this fits

Piwik PRO is a **web destination** in the walkerOS flow:

## Installation[​](#installation "Direct link to Installation")

```
npm install @walkeros/web-destination-piwikpro
```

* Integrated
* Bundled

```
import { startFlow } from '@walkeros/collector';
import { destinationPiwikPro } from '@walkeros/web-destination-piwikpro';

await startFlow({
  destinations: {
    piwikpro: {
      code: destinationPiwikPro,
      config: {
        settings: {
          appId: 'XXX-XXX-XXX-XXX-XXX',
          url: 'https://your_account_name.piwik.pro/',
        },
      },
    },
  },
});
```

Add to your `flow.json` destinations:

```
"destinations": {
  "piwikpro": {
    "package": "@walkeros/web-destination-piwikpro",
    "config": {
      "settings": {
        "appId": "XXX-XXX-XXX-XXX-XXX",
        "url": "https://your_account_name.piwik.pro/"
      }
    }
  }
}
```

[See bundled mode setup](https://www.walkeros.io/docs/getting-started/modes/bundled.md) | [CLI reference](https://www.walkeros.io/docs/apps/cli.md)

## Configuration[​](#configuration "Direct link to Configuration")

This <!-- -->destination<!-- --> uses the standard <!-- -->destination<!-- --> config wrapper (consent, data, env, id, ...). For the shared fields see [destination<!-- --> configuration](https://www.walkeros.io/docs/destinations.md#configuration). Package-specific fields live under `config.settings` and are listed below.

## Settings[​](#settings "Direct link to Settings")

| Property       | Type      | Description                                    | More |
| -------------- | --------- | ---------------------------------------------- | ---- |
| `appId*`       | `string`  | ID of the Piwik PRO site                       |      |
| `url*`         | `string`  | URL of your Piwik PRO account                  |      |
| `linkTracking` | `boolean` | Enables/Disables download and outlink tracking |      |

\* Required fields

## Mapping[​](#mapping "Direct link to Mapping")

Per-event rules under `config.mapping`. For the standard rule fields (consent, condition, data, batch, name, policy) see [mapping](https://www.walkeros.io/docs/mapping.md).

| Property    | Type     | Description                           | More |
| ----------- | -------- | ------------------------------------- | ---- |
| `goalId*`   | `string` | ID to count the event as a goal       |      |
| `goalValue` | `string` | Property to be used as the goal value |      |

\* Required fields

## Examples

### Cart update

A cart view fires Piwik PRO ecommerceCartUpdate with nested products, total value, and currency code.

Event

```
{
  "name": "cart view",
  "data": {
    "currency": "EUR",
    "value": 840
  },
  "context": {
    "shopping": [
      "cart",
      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,
        "quantity": 2
      },
      "context": {
        "shopping": [
          "cart",
          0
        ]
      },
      "nested": []
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "c32f8dee4a96be6a",
  "trigger": "load",
  "entity": "cart",
  "action": "view",
  "timestamp": 1700000303,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
```

Mapping

```
{
  "name": "ecommerceCartUpdate",
  "data": {
    "set": [
      {
        "loop": [
          "nested",
          {
            "condition": {
              "$code": "e=>g(e)&&\"product\"===e.entity"
            },
            "map": {
              "sku": "data.id",
              "name": "data.name",
              "price": "data.price",
              "quantity": {
                "value": 1
              },
              "variant": {
                "key": "data.color"
              },
              "customDimensions": {
                "map": {
                  "1": "data.size"
                }
              }
            }
          }
        ]
      },
      "data.value",
      {
        "map": {
          "currencyCode": {
            "value": "EUR"
          }
        }
      }
    ]
  }
}
```

Out

```
ecommerceCartUpdate([
  {
    "sku": "ers",
    "name": "Everyday Ruck Snack",
    "price": 420,
    "quantity": 1,
    "variant": "black",
    "customDimensions": {
      "1": "l"
    }
  }
], 840, {
  "currencyCode": "EUR"
})
```

### Custom event with goal

A promotion visible event fires Piwik PRO trackEvent and then trackGoal to record a goal conversion.

Event

```
{
  "name": "promotion visible",
  "data": {
    "name": "Setting up tracking easily",
    "position": "hero"
  },
  "context": {
    "ab_test": [
      "engagement",
      0
    ]
  },
  "globals": {
    "pagegroup": "homepage"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [
    {
      "entity": "child",
      "data": {
        "is": "subordinated"
      }
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "93bf0165d5d34891",
  "trigger": "visible",
  "entity": "promotion",
  "action": "visible",
  "timestamp": 1700000304,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
```

Mapping

```
{
  "name": "trackEvent",
  "settings": {
    "goalId": "goal_1"
  },
  "data": {
    "set": [
      "data.name",
      "data.position"
    ]
  }
}
```

Out

```
trackEvent("Setting up tracking easily", "hero");

trackGoal("goal_1", null)
```

### Add to cart

A product add fires Piwik PRO ecommerceAddToCart with the added item and currency code.

Event

```
{
  "name": "product add",
  "data": {
    "id": "ers",
    "name": "Everyday Ruck Snack",
    "color": "black",
    "size": "l",
    "price": 420
  },
  "context": {
    "shopping": [
      "intent",
      0
    ]
  },
  "globals": {
    "pagegroup": "shop"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [],
  "consent": {
    "functional": true
  },
  "id": "0bc13e3fc55029e2",
  "trigger": "click",
  "entity": "product",
  "action": "add",
  "timestamp": 1700000301,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
```

Mapping

```
{
  "name": "ecommerceAddToCart",
  "data": {
    "set": [
      {
        "set": [
          {
            "map": {
              "sku": "data.id",
              "name": "data.name",
              "price": "data.price",
              "quantity": {
                "value": 1
              },
              "variant": {
                "key": "data.color"
              },
              "customDimensions": {
                "map": {
                  "1": "data.size"
                }
              }
            }
          }
        ]
      },
      {
        "map": {
          "currencyCode": {
            "value": "EUR"
          }
        }
      }
    ]
  }
}
```

Out

```
ecommerceAddToCart([
  {
    "sku": "ers",
    "name": "Everyday Ruck Snack",
    "price": 420,
    "quantity": 1,
    "variant": "black",
    "customDimensions": {
      "1": "l"
    }
  }
], {
  "currencyCode": "EUR"
})
```

### Ecommerce order

A completed order calls Piwik PRO ecommerceOrder with line items, order totals, and currency code.

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": "9fa6cd5d42f6cf80",
  "trigger": "load",
  "entity": "order",
  "action": "complete",
  "timestamp": 1700000300,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
```

Mapping

```
{
  "name": "ecommerceOrder",
  "data": {
    "set": [
      {
        "loop": [
          "nested",
          {
            "condition": {
              "$code": "e=>g(e)&&\"product\"===e.entity"
            },
            "map": {
              "sku": "data.id",
              "name": "data.name",
              "price": "data.price",
              "quantity": {
                "value": 1
              },
              "variant": {
                "key": "data.color"
              },
              "customDimensions": {
                "map": {
                  "1": "data.size"
                }
              }
            }
          }
        ]
      },
      {
        "map": {
          "orderId": "data.id",
          "grandTotal": "data.total",
          "tax": "data.taxes",
          "shipping": "data.shipping"
        }
      },
      {
        "map": {
          "currencyCode": {
            "value": "EUR"
          }
        }
      }
    ]
  }
}
```

Out

```
ecommerceOrder([
  {
    "sku": "ers",
    "name": "Everyday Ruck Snack",
    "price": 420,
    "quantity": 1,
    "variant": "black",
    "customDimensions": {
      "1": "l"
    }
  },
  {
    "sku": "cc",
    "name": "Cool Cap",
    "price": 42,
    "quantity": 1,
    "customDimensions": {
      "1": "one size"
    }
  }
], {
  "orderId": "0rd3r1d",
  "grandTotal": 555,
  "tax": 73.76,
  "shipping": 5.22
}, {
  "currencyCode": "EUR"
})
```

### Initialization

Destination bootstrap loads the Piwik PRO tracker and configures the tracker URL and app id.

Event

```
{
  "loadScript": true,
  "settings": {
    "appId": "XXX-XXX-XXX-XXX-XXX",
    "url": "https://your_account_name.piwik.pro/"
  }
}
```

Out

```
_paq.push([
  "setTrackerUrl",
  "https://your_account_name.piwik.pro/ppms.php"
]);

_paq.push([
  "setSiteId",
  "XXX-XXX-XXX-XXX-XXX"
]);

_paq.push([
  "enableLinkTracking"
])
```

### Page view

A page view fires Piwik PRO trackPageView with the page title resolved from event data.

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": "f3f38565651ea52f",
  "trigger": "load",
  "entity": "page",
  "action": "view",
  "timestamp": 1700000305,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
```

Mapping

```
{
  "data": "data.title"
}
```

Out

```
trackPageView("walkerOS documentation")
```

### Product detail view

A product view fires Piwik PRO ecommerceProductDetailView with a single-item array and currency code.

Event

```
{
  "name": "product view",
  "data": {
    "id": "ers",
    "name": "Everyday Ruck Snack",
    "color": "black",
    "size": "l",
    "price": 420
  },
  "context": {
    "shopping": [
      "detail",
      0
    ]
  },
  "globals": {
    "pagegroup": "shop"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [],
  "consent": {
    "functional": true
  },
  "id": "73fe5e7324d23e89",
  "trigger": "load",
  "entity": "product",
  "action": "view",
  "timestamp": 1700000302,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
```

Mapping

```
{
  "name": "ecommerceProductDetailView",
  "data": {
    "set": [
      {
        "set": [
          {
            "map": {
              "sku": "data.id",
              "name": "data.name",
              "price": "data.price",
              "quantity": {
                "value": 1
              },
              "variant": {
                "key": "data.color"
              },
              "customDimensions": {
                "map": {
                  "1": "data.size"
                }
              }
            }
          }
        ]
      },
      {
        "map": {
          "currencyCode": {
            "value": "EUR"
          }
        }
      }
    ]
  }
}
```

Out

```
ecommerceProductDetailView([
  {
    "sku": "ers",
    "name": "Everyday Ruck Snack",
    "price": 420,
    "quantity": 1,
    "variant": "black",
    "customDimensions": {
      "1": "l"
    }
  }
], {
  "currencyCode": "EUR"
})
```