PrivatusAnalytics (Privatus Analytics v1.0.0)

Copy Markdown View Source

Adds the cookieless Privatus Analytics tracking script to Phoenix and Plug apps.

The package only prints HTML: the browser script tag and HTML attributes. It never sends events from your server, sets no cookies and never reads IP addresses or user agents.

The tag

Product analytics helpers

  • event_attrs/2 sends an event when an element is clicked (or a form is submitted).
  • click_attrs/1 names an element for click maps.
  • put_props/2 and the :props option set page properties.
  • props_json/1 gives page properties as JSON, for a LiveView hook.

See PrivatusAnalytics.Config for every setting and how the environment is chosen.

Summary

Types

attrs()

Attributes as {name, value} pairs, ready for {...} in HEEx.

options()

Options for the tag. Any setting from PrivatusAnalytics.Config plus :nonce, :props, :queue_stub and :conn.

props()

Event or page properties, as a map or keyword list.

Functions

click_attrs(name)

The attribute that names an element for click maps.

click_attrs_html(name)

Like click_attrs/1, as safe HTML for EEx.

click_attrs_string(name)

Like click_attrs/1, as a plain escaped string.

enabled?(opts \\ [])

Whether the tag prints for these options (site id set and enabled).

event_attrs(name, props \\ [])

Attributes that send an event when the element is clicked. On a <form> the event is sent when the form is submitted.

event_attrs_html(name, props \\ [])

Like event_attrs/2, as safe HTML for EEx: <button <%= event_attrs_html("Export CSV") %>>.

event_attrs_string(name, props \\ [])

Like event_attrs/2, as a plain escaped string of attributes.

props_json(props)

Page properties as a JSON object string, cleaned the same way as the tag does. Handy for a LiveView hook: data-privatus-props={PrivatusAnalytics.props_json(%{plan: @plan})}.

put_props(conn, props)

Adds page properties for this request. They are sent with every pageview and event on the page. Use groups (plan, role), never anything that names a person.

queue_stub(opts \\ [])

The official queue stub script, so privatus.track calls made before the tracker loads are kept. Also printed by the tag with queue_stub: true.

tag(opts \\ [])

The script tag as safe HTML ({:safe, iodata}), ready for EEx and HEEx.

tag_string(opts \\ [])

The script tag as a plain string. Empty when nothing should print.

Types

attrs()

@type attrs() :: [{String.t(), String.t()}]

Attributes as {name, value} pairs, ready for {...} in HEEx.

options()

@type options() :: keyword() | map()

Options for the tag. Any setting from PrivatusAnalytics.Config plus :nonce, :props, :queue_stub and :conn.

props()

@type props() :: map() | keyword()

Event or page properties, as a map or keyword list.

Functions

click_attrs(name)

@spec click_attrs(String.t() | atom()) :: attrs()

The attribute that names an element for click maps.

<a href="/signup" {PrivatusAnalytics.click_attrs("pricing.cta")}>Start</a>

The name must be 1 to 100 letters, digits or _ . : -. Any other name returns [] (and logs a warning outside production).

click_attrs_html(name)

@spec click_attrs_html(String.t() | atom()) :: {:safe, String.t()}

Like click_attrs/1, as safe HTML for EEx.

click_attrs_string(name)

@spec click_attrs_string(String.t() | atom()) :: String.t()

Like click_attrs/1, as a plain escaped string.

enabled?(opts \\ [])

@spec enabled?(options()) :: boolean()

Whether the tag prints for these options (site id set and enabled).

event_attrs(name, props \\ [])

@spec event_attrs(String.t() | atom(), props()) :: attrs()

Attributes that send an event when the element is clicked. On a <form> the event is sent when the form is submitted.

<button {PrivatusAnalytics.event_attrs("Export CSV", format: "csv")}>Export</button>

Returns [] when the name is empty. Printed even when the tag is off, so your HTML is the same in development and production.

event_attrs_html(name, props \\ [])

@spec event_attrs_html(String.t() | atom(), props()) :: {:safe, String.t()}

Like event_attrs/2, as safe HTML for EEx: <button <%= event_attrs_html("Export CSV") %>>.

event_attrs_string(name, props \\ [])

@spec event_attrs_string(String.t() | atom(), props()) :: String.t()

Like event_attrs/2, as a plain escaped string of attributes.

props_json(props)

@spec props_json(props()) :: String.t()

Page properties as a JSON object string, cleaned the same way as the tag does. Handy for a LiveView hook: data-privatus-props={PrivatusAnalytics.props_json(%{plan: @plan})}.

put_props(conn, props)

@spec put_props(conn, props()) :: conn when conn: %{private: map()}

Adds page properties for this request. They are sent with every pageview and event on the page. Use groups (plan, role), never anything that names a person.

conn |> PrivatusAnalytics.put_props(%{plan: "pro", role: "admin"})

The tag and the Plug read them from the conn. Calls merge.

queue_stub(opts \\ [])

@spec queue_stub(keyword()) :: {:safe, String.t()}

The official queue stub script, so privatus.track calls made before the tracker loads are kept. Also printed by the tag with queue_stub: true.

tag(opts \\ [])

@spec tag(options()) :: {:safe, String.t()}

The script tag as safe HTML ({:safe, iodata}), ready for EEx and HEEx.

<%= PrivatusAnalytics.tag(nonce: @csp_nonce) %>

Without a site id or when the tag is not enabled, prints only the queue stub (with queue_stub: true) or nothing.

tag_string(opts \\ [])

@spec tag_string(options()) :: String.t()

The script tag as a plain string. Empty when nothing should print.