# `PrivatusAnalytics`
[🔗](https://github.com/Privatus-Analytics/elixir/blob/v1.0.0/lib/privatus_analytics.ex#L1)

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

  * `PrivatusAnalytics.Components.tag/1` for HEEx layouts.
  * `tag/1` (safe HTML) and `tag_string/1` (plain string) for EEx or anything else.
  * `PrivatusAnalytics.Plug` adds the tag before `</head>` for you.

## 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.

# `attrs`

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

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

# `options`

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

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

# `props`

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

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

# `click_attrs`

```elixir
@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`

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

Like `click_attrs/1`, as safe HTML for EEx.

# `click_attrs_string`

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

Like `click_attrs/1`, as a plain escaped string.

# `enabled?`

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

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

# `event_attrs`

```elixir
@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`

```elixir
@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`

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

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

# `props_json`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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`

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

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

---

*Consult [api-reference.md](api-reference.md) for complete listing*