Event Tracking & Analytics

6 min

the events api provides transparency into how helpline information is displayed to and used by end users this feature captures two discrete, timestamped signals to measure the user journey helplinedisplay captures when a helpline is shown to a user helplineclick captures when a user takes action to contact a helpline key benefits billing transparency provides transparency for throughline and customers to ensure billing is based on verified usage data compliance & impact reporting through exportable analytics, simplifies reporting to regulators and stakeholders based on documented reach and user activity load management allows throughline to monitor and manage load across helplines to ensure service availability conversion insights uses a unique identifier to calculate the click through rate (ctr) from display to contact data flow the following diagram illustrates how event data travels from your application to the throughline analytics dashboard %%{init { "theme" "base", "themevariables" { "fontfamily" "lato, system ui, sans serif", "fontsize" "15px", "linecolor" "#9ba3aa", "primarytextcolor" "#0f2027", "clusterbkg" "#ffffff", "clusterborder" "#c2c9cc", "edgelabelbackground" "#ffffff" }, "flowchart" { "curve" "basis", "nodespacing" 60, "rankspacing" 75, "padding" 18, "htmllabels" true } }}%% flowchart tb client("\client application\\ \partner system / 3rd party integration\") subgraph throughline\["\ throughline systems\ "] direction tb display("\post /v2/events/helplinedisplay\\ \helplineid + sessionid + timestamp\") clickevt("\post /v2/events/helplineclick\\ \+ contactmethod required\") dashboard("\dashboard\\ \looker dashboard with csv export\") end client >|"display"| display client >|"click"| clickevt display > dashboard clickevt > dashboard %% ── throughline brand styling ── classdef entry fill #ede9e1,stroke #d8d1c4,color #0f2027,rx 12,ry 12; classdef api fill #eef4f6,stroke #7bb5b9,color #0f2027,rx 12,ry 12; classdef dash fill #dcebec,stroke #2b8e94,color #0f2027,stroke width 1 5px,rx 12,ry 12; class client entry; class display,clickevt api; class dashboard dash; style throughline fill #fbfdfe,stroke #c2c9cc,stroke width 1 5px,stroke dasharray 6 5; %% coral for user initiated events, teal for internal flow linkstyle 0,1 stroke #e8886c,stroke width 2 5px; linkstyle 2,3 stroke #2b8e94,stroke width 2 5px; events endpoints these endpoints are used to report the two core signals detailed schemas are available in the api reference docid\ s7xve1bi ghsilgti9czm method endpoint required parameters description post /v2/events/helplinedisplay helplineid (string) sessionid (string) timestamp (iso 8601) report when a helpline is displayed to a user post /v2/events/helplineclick helplineid (string) sessionid (string) timestamp (iso 8601) contactmethod (enum) report when a user clicks a contact method for a helpline parameter definitions the events api utilizes two primary identifiers to link these signals helplineid this string must match the unique id for the helpline entity retrieved from the /helplines endpoint sessionid an opaque string provided by the client to link a "display" event to a "click" event flexibility you may use any identifier you prefer, such as a guid or a hashed string consistency the id must remain unique and consistent for the duration of a single user session to allow for accurate conversion rate calculations anonymity because this id is partner provided and contains no pii, it ensures user anonymity while still providing measurable impact tracking contact method values the contactmethod field is an enum used to report which specific channel a user chose to contact \\ \\ phone phone call sms sms / text message onlinechat online chat website visit to the website tty tty / relay call whatsapp whatsapp reportingform online reporting form privacy & quota information no personal data no personally identifiable information is collected at any stage service level data events record what happened (helpline id), how (click), and when (timestamp) never who quota exemption event api calls do not count against the standard api display quota batch upload we also support batch event uploads, which is useful if you’re unable to deliver events in real time this is an asynchronous process, consisting of an initial upload followed by a status poll method endpoint body content description post /v2/events/batch an array of helplinedisplay and helplineclick events upload up to 1m/150mib of events (whichever is smaller) and receive a job id get /v2/events/batch/jobs/\ jobid none get the in progress status or the terminal result once the job is complete, the status payload will tell you how many events were valid, how many failed validation, and what was wrong with each of them more details are available in the api reference docid\ pm xobdzfl1j7twjpzrvi by default, valid events are stored and invalid events are rejected; you should investigate and fix the failures and then re submit them individually it’s important in this default mode that you don’t re submit events that were accepted, as they will cause duplication in your reporting however if you’d prefer, you can specify on upload that the batch be treated atomically in this mode, even one failure will reject storage of the entire batch, allowing you to fix the errors and then resubmit the entire payload without risk of duplication