--- title: User tracking slug: ref/user-tracking docTags: createdAt: 2023-12-06T11:09:37.132Z --- You can optionally track user behaviour and register all actions a user takes in the webshop. This includes adding tickets to orders, viewing the basket, starting checkout and confirming the order. User tracking in Ticketmatic is not an out of the box, standalone solution. The user actions in the Ticketmatic webshop are only a part of the complete user behaviour on your channels (website, app,...). The main idea is that the user actions in Ticketmatic can be integrated in this larger picture. Setting this up requires technical knowledge and you might need the help of a partner to implement this for your specific situation. :::hint{type="success"} Good candidates are: - your website builder - your website-ticketing integrator - your marketing partner ::: In order to be compliant with privacy laws like GDPR, this user tracking is completely optional. As data controller you should verify whether you need to get consent from the user to track and process this information. User tracking data is stored exclusively in Ticketmatic, no external services are involved. Ticketmatic webshop pages will not contain any other trackers or scripts and Ticketmatic will only use cookies that are essential for processing the order and authenticating the user. ## How to activate tracking If you get the right consent from the user, you can activate tracking for a widget or sales flow by passing an extra querystring parameter `ref`. This parameter is used to link the user actions in Ticketmatic with the actions of this user on your other channels. As value for the `ref` parameter, you can for example specify a userid or clientid that is used on the website. This value will be stored together with the user actions, allowing you to make the link when retrieving the data. :::hint{type="info"} Ticketmatic will not process or use this value in any way and will store and return this unaltered, so you are free to use this as you want. ::: If you don't pass a `ref` parameter, user actions will **not** be tracked for that widget or salesflow session. The `ref` parameter does not need to be included in the signature for widgets, so you can simply append it to a generated widget or ticket sales flow link. :::hint{type="success"} For example: If you have this sales flow url: `https://test.ticketmatic.com/widgets/demo_tm3/flow/saleslink?event=130716474767&l=en` You can simply append a ref parameter: `https://test.ticketmatic.com/widgets/demo_tm3/flow/saleslink?event=130716474767&l=en&ref=user1234` ::: ## How to retrieve and process the user tracking data All user tracking data is stored by Ticketmatic and can be retrieved using the API. In order to continuously consume the stream of user tracking data, you will need to implement a long-running process or periodic job. By polling the eventstream endpoint you can iterate over all user tracking data and process it (for example by sending it to Google Analytics or other analytics tools). User tracking data is available almost instantly on the eventstream, so there is very little delay between the user action and you processing this action. ### Polling the eventstream Calling the eventstream endpoint is easy: ::::hint{type="success"} For example: :::BlockQuote `curl -u ':' 'https://apps.ticketmatic.com/api/1//eventstream'` ::: :::: The call will return an object with 3 keys: - results - nextid - moreresults **results** contains an array of eventstream items. Each item is an object with a set of fixed keys, and one of the keys is the `id`. Each eventstream item is assigned a unique (and ascending) id. **nextid** indicates the id to start on when you next call the eventstream, and **moreresults** is a boolean an indicates if there are more eventstream items waiting for you. Calling eventstream without parameters returns the oldest available eventstream items. You can pass a parameter id to retrieve all items from that id on: ::::hint{type="success"} For example: :::BlockQuote `curl -u ':' 'https://test.ticketmatic.com/api/1//eventstream?id='` ::: :::: So to consume the eventstream: - call the endpoint - process the results - if `moreresults` is true, immediately call the endpoint again with `nextid` as parameter and loop - if `moreresults` is false, wait 5-60 seconds and loop :::hint{type="warning"} Ticketmatic stores eventstream items for 4 hours. So you should process the items within that timeframe. ::: ### Processing the results Each eventstream result item is an object containing keys: - id - ts - type - data **id** is the unique id for this item, and *ts* is the timestamp in ISO 8601 format (UTC). **type** defines what the eventstream item is, and is a value from this list: - webshop\:add\_tickets - webshop\:add\_products - webshop\:remove\_tickets - webshop\:remove\_products - webshop\:checkout\_start - webshop\:checkout\_addcustomerinfo - webshop\:checkout\_adddeliveryinfo - webshop\:checkout\_addpaymentinfo - webshop\:checkout\_initiatepayment - webshop\:checkout\_confirm - webshop\:pageview Other types might be added in the future, so make sure to filter on this and process only the items relevant to you. Depending on the type, relevant information is returned in the **data** property. All items wil contain the `ref` key with the value you passed in the querystring. ### webshop\:add\_tickets When a user adds tickets to the basket. The `tickets` key contains an array with one object for each added ticket. The `order` key contains the state of the order after the tickets were added. ```json { "id": "1661358385340-0", "ts": "2022-09-13T11:46:25", "type": "webshop:add_tickets", "data": { "tickets": [ { "id": "10634", "price": "20", "servicecharge": "0", "tickettypepriceid": "580", "tickettypeid": "92", "tickettypename": "Tickets", "pricetypeid": "10000", "pricetypename": "Normal", "eventid": "10003", "eventname": "Dance performance 2" }, { "id": "10635", "price": "20", "servicecharge": "0", "tickettypepriceid": "580", "tickettypeid": "92", "tickettypename": "Tickets", "pricetypeid": "10000", "pricetypename": "Normal", "eventid": "10003", "eventname": "Dance performance 2" } ], "order": { "id": "398", "saleschannelid": "10000", "customerid": null, "deliveryscenarioid": null, "paymentscenarioid": null, "totalamount": "40", "tickets": [ { "id": "10634", "price": "20", "servicecharge": "0", "tickettypepriceid": "580", "tickettypeid": "92", "tickettypename": "Tickets", "pricetypeid": "10000", "pricetypename": "Normal", "eventid": "10003", "eventname": "Dance performance 2" }, { "id": "10635", "price": "20", "servicecharge": "0", "tickettypepriceid": "580", "tickettypeid": "92", "tickettypename": "Tickets", "pricetypeid": "10000", "pricetypename": "Normal", "eventid": "10003", "eventname": "Dance performance 2" } ], "products": [ ] }, "ref": "user12345" } } ``` ### webshop\:remove\_tickets When a user removes tickets from the basket. The `tickets` key contains an array with one object for each removed ticket. The `order` key contains the state of the order after the tickets were added. :::hint{type="info"} Remark that when a user revisits the addtickets page after previously adding tickets and changes the number of tickets he wants, this can result in a `webshop:remove_tickets` action for **all** tickets and then a `webshop:add_tickets` action for the new number of tickets. ::: ```json { "id": "1661359082144-0", "ts": "2022-09-13T11:58:02", "type": "webshop:remove_tickets", "data": { "tickets": [ { "id": "10635", "price": "20", "servicecharge": "0", "tickettypepriceid": "580", "tickettypeid": "92", "tickettypename": "Tickets", "pricetypeid": "10000", "pricetypename": "Normal", "eventid": "10003", "eventname": "Dance performance 2" } ], "order": { "id": "398", "saleschannelid": "10000", "customerid": null, "deliveryscenarioid": null, "paymentscenarioid": null, "totalamount": "40", "tickets": [ { "id": "10636", "price": "20", "servicecharge": "0", "tickettypepriceid": "580", "tickettypeid": "92", "tickettypename": "Tickets", "pricetypeid": "10000", "pricetypename": "Normal", "eventid": "10003", "eventname": "Dance performance 2" }, { "id": "10637", "price": "20", "servicecharge": "0", "tickettypepriceid": "580", "tickettypeid": "92", "tickettypename": "Tickets", "pricetypeid": "10000", "pricetypename": "Normal", "eventid": "10003", "eventname": "Dance performance 2" } ], "products": [ ] }, "ref": "user12345" } } ``` ### webshop\:add\_products When a user adds products to the basket. The `products` key contains an array with one object for each added product. The `order` key contains the state of the order after the products were added. ```json { "id": "1661359739037-0", "ts": "2022-09-13T12:08:59", "type": "webshop:add_products", "data": { "products": [ { "id": "10001", "productid": "10000", "price": "100", "producttype": "26002", "productname": "Gift voucher" }, { "id": "10002", "productid": "10000", "price": "100", "producttype": "26002", "productname": "Gift voucher" } ], "order": { "id": "398", "saleschannelid": "10000", "customerid": null, "deliveryscenarioid": null, "paymentscenarioid": null, "totalamount": "240", "tickets": [ { "id": "10636", "price": "20", "servicecharge": "0", "tickettypepriceid": "580", "tickettypeid": "92", "tickettypename": "Tickets", "pricetypeid": "10000", "pricetypename": "Normal", "eventid": "10003", "eventname": "Dance performance 2" }, { "id": "10637", "price": "20", "servicecharge": "0", "tickettypepriceid": "580", "tickettypeid": "92", "tickettypename": "Tickets", "pricetypeid": "10000", "pricetypename": "Normal", "eventid": "10003", "eventname": "Dance performance 2" } ], "products": [ { "id": "10001", "productid": "10000", "price": "100", "producttype": "26002", "productname": "Gift voucher" }, { "id": "10002", "productid": "10000", "price": "100", "producttype": "26002", "productname": "Gift voucher" } ] }, "ref": "user12345" } } ``` ### webshop\:remove\_products When a user removes products from the basket. The `products` key contains an array with one object for each removed product. The `order` key contains the state of the order after the products were removed. ```json { "id": "1661439554553-0", "ts": "2022-09-13T10:19:14", "type": "webshop:remove_products", "data": { "products": [ { "id": "10004", "productid": "10000", "price": "100", "producttype": "26002", "productname": "Gift voucher" } ], "order": { "id": "401", "saleschannelid": "10000", "customerid": null, "deliveryscenarioid": "10000", "paymentscenarioid": "10001", "totalamount": "100", "tickets": [ ], "products": [ { "id": "10003", "productid": "10000", "price": "100", "producttype": "26002", "productname": "Gift voucher" } ] }, "ref": "user23456" } } ``` ### webshop\:checkout\_start When a user starts the checkout process. The `order` key contains the state of the order. ```json { "id": "1661359739319-0", "ts": "2022-09-13T12:08:59", "type": "webshop:checkout_start", "data": { "order": { "id": "398", "saleschannelid": "10000", "customerid": null, "deliveryscenarioid": null, "paymentscenarioid": null, "totalamount": "240", "tickets": [ { "id": "10636", "price": "20", "servicecharge": "0", "tickettypepriceid": "580", "tickettypeid": "92", "tickettypename": "Tickets", "pricetypeid": "10000", "pricetypename": "Normal", "eventid": "10003", "eventname": "Dance performance 2" }, { "id": "10637", "price": "20", "servicecharge": "0", "tickettypepriceid": "580", "tickettypeid": "92", "tickettypename": "Tickets", "pricetypeid": "10000", "pricetypename": "Normal", "eventid": "10003", "eventname": "Dance performance 2" } ], "products": [ { "id": "10001", "productid": "10000", "price": "100", "producttype": "26002", "productname": "Gift voucher" }, { "id": "10002", "productid": "10000", "price": "100", "producttype": "26002", "productname": "Gift voucher" } ] }, "ref": "user12345" } } ``` ### webshop\:checkout\_addcustomerinfo When a user adds customer info during the checkout process. The `order` key contains the state of the order. `order.customerid` contains the id of the customer. ```json { "id": "1661360224312-0", "ts": "2022-09-13T12:17:04", "type": "webshop:checkout_addcustomerinfo", "data": { "order": { "id": "398", "saleschannelid": "10000", "customerid": "10016", "deliveryscenarioid": "10000", "paymentscenarioid": "10001", "totalamount": "240", "tickets": [ { "id": "10636", "price": "20", "servicecharge": "0", "tickettypepriceid": "580", "tickettypeid": "92", "tickettypename": "Tickets", "pricetypeid": "10000", "pricetypename": "Normal", "eventid": "10003", "eventname": "Dance performance 2" }, { "id": "10637", "price": "20", "servicecharge": "0", "tickettypepriceid": "580", "tickettypeid": "92", "tickettypename": "Tickets", "pricetypeid": "10000", "pricetypename": "Normal", "eventid": "10003", "eventname": "Dance performance 2" } ], "products": [ { "id": "10001", "productid": "10000", "price": "100", "producttype": "26002", "productname": "Gift voucher" }, { "id": "10002", "productid": "10000", "price": "100", "producttype": "26002", "productname": "Gift voucher" } ] }, "ref": "user12345" } } ``` ### webshop\:checkout\_adddeliveryinfo When a user adds delivery info during the checkout process. The `order` key contains the state of the order. `order.deliveryscenarioid` contains the id of the selected delivery scenario. ```json { "id": "1664159739545-0", "ts": "2022-09-13T12:08:59", "type": "webshop:checkout_adddeliveryinfo", "data": { "order": { "id": "398", "saleschannelid": "10000", "customerid": null, "deliveryscenarioid": "10000", "paymentscenarioid": null, "totalamount": "240", "tickets": [ { "id": "10636", "price": "20", "servicecharge": "0", "tickettypepriceid": "580", "tickettypeid": "92", "tickettypename": "Tickets", "pricetypeid": "10000", "pricetypename": "Normal", "eventid": "10003", "eventname": "Dance performance 2" }, { "id": "10637", "price": "20", "servicecharge": "0", "tickettypepriceid": "580", "tickettypeid": "92", "tickettypename": "Tickets", "pricetypeid": "10000", "pricetypename": "Normal", "eventid": "10003", "eventname": "Dance performance 2" } ], "products": [ { "id": "10001", "productid": "10000", "price": "100", "producttype": "26002", "productname": "Gift voucher" }, { "id": "10002", "productid": "10000", "price": "100", "producttype": "26002", "productname": "Gift voucher" } ] }, "ref": "user12345" } } ``` ### webshop\:checkout\_addpaymentinfo When a user adds payment info during the checkout process. The `order` key contains the state of the order. `order.paymentscenarioid` contains the id of the selected payment scenario. ### webshop\:checkout\_initiatepayment When a user start the payment process and is redirected to the PSP. The `order` key contains the state of the order. ```json { "id": "1664310309368-0", "ts": "2022-09-13T12:18:29", "type": "webshop:checkout_initiatepayment", "data": { "order": { "id": "398", "saleschannelid": "10000", "customerid": "10016", "deliveryscenarioid": "10000", "paymentscenarioid": "10001", "totalamount": "240", "tickets": [ { "id": "10636", "price": "20", "servicecharge": "0", "tickettypepriceid": "580", "tickettypeid": "92", "tickettypename": "Tickets", "pricetypeid": "10000", "pricetypename": "Normal", "eventid": "10003", "eventname": "Dance performance 2" }, { "id": "10637", "price": "20", "servicecharge": "0", "tickettypepriceid": "580", "tickettypeid": "92", "tickettypename": "Tickets", "pricetypeid": "10000", "pricetypename": "Normal", "eventid": "10003", "eventname": "Dance performance 2" } ], "products": [ { "id": "10001", "productid": "10000", "price": "100", "producttype": "26002", "productname": "Gift voucher" }, { "id": "10002", "productid": "10000", "price": "100", "producttype": "26002", "productname": "Gift voucher" } ] }, "ref": "user12345" } } ``` ### webshop\:checkout\_confirm When payment is confirmed and the user returns to Ticketmatic and sees the order detail page. The `order` key contains the state of the order. ```json { "id": "1664419049115-0", "ts": "2022-09-13T10:10:49", "type": "webshop:checkout_confirm", "data": { "order": { "id": "400", "saleschannelid": "10000", "customerid": "10016", "deliveryscenarioid": "10000", "paymentscenarioid": "10001", "totalamount": "40", "tickets": [ { "id": "10640", "price": "20", "servicecharge": "0", "tickettypepriceid": "580", "tickettypeid": "92", "tickettypename": "Tickets", "pricetypeid": "10000", "pricetypename": "Normal", "eventid": "10003", "eventname": "Dance performance 2" }, { "id": "10641", "price": "20", "servicecharge": "0", "tickettypepriceid": "580", "tickettypeid": "92", "tickettypename": "Tickets", "pricetypeid": "10000", "pricetypename": "Normal", "eventid": "10003", "eventname": "Dance performance 2" } ], "products": [ ] }, "ref": "user23456" } } ``` ### webshop\:pageview When a user views a page in the widget. The **page** key returns the name of the visited page. The **params** object returns the widget parameters for the page. ```json { "id": "1661438970777-0", "ts": "2022-09-13T10:09:30", "type": "webshop:pageview", "data": { "page": "summary", "params": { "edit": "yes", "flow": "basketwithcheckout", "skinid": "10000", "returnurl": "https://www.ticketmatic.com/", "saleschannelid": "10000", "reservemoretickets": "yes", "event": "10003", "withauthentication": "no", "subscribe": "no", "detail": "ticketdetails", "panels": "voucher,customer,delivery,payment,extrainfo", "oncompletion": "orderdetail", "requiredfields": "", "product": "", "ticketcustomfields": "", "requiredticketcustomfields": "", "ticketinfo": "", "extraevents": "", "extraproducts": "", "promocode": null }, "orderid": "400", "customerid": "10016", "ref": "user23456" } } ```