Documentation
Menu

Identify users

Attach your app's user ids to visits, for sessions and retention. Opt-in.

By default every visitor is anonymous, and the visitor id changes every day. If your site has signed-in users, you can tell Oxidt Analytics who they are. Their visits then show the user id on Sessions, and Retention shows how many of them come back week after week.

Identification is off by default. A user id is personal data, so turning it on is your decision (see Privacy).

Turn it on

In the website's Settings, switch on Identify signed-in users and save. While it is off, identify calls are accepted and dropped.

Call identify

Call window.oxidt.identify with your user's id on every page load while they are signed in:

js
window.oxidt.identify(user.id, { plan: "pro" });
  • The id is up to 200 characters. Pass an opaque internal id, such as a database id or UUID. Never pass an email address or a name.
  • Properties are optional and follow the custom event rules. Later calls update them.
  • The tracker stores nothing on the device. A visit is linked to the user from the first identify call in it, so call it on every page load, not only at sign-in.

If you call it before script.js has loaded, use the queue:

html
<script>
  window.oxidt = window.oxidt || { q: [], iq: [] };
  window.oxidt.track = window.oxidt.track || function () { window.oxidt.q.push(arguments); };
  window.oxidt.identify = window.oxidt.identify || function () { window.oxidt.iq.push(arguments); };
</script>

Erase a user

To answer a deletion request, enter the user id under Settings → Erase a user. This deletes the id and every visit, event and payment linked to it. The same works with an API key from the website's organization (admin role):

bash
curl -X DELETE https://analytics.example.com/api/websites/YOUR_SITE_ID/identities/USER_ID \
  -H "Authorization: Bearer oat_…"

The response says whether the user was known and how many visits were deleted: {"identity": true, "sessions": 3}.

Turn it off

Switching identification off deletes every stored user id at once. The visits and revenue stay, anonymous again.

Revenue

Payments are linked to the payer's latest visit before paying, so Retention can show revenue by source. Pass the same id you give oxidt.identify to Stripe:

  • Checkout (one-time payments): set client_reference_id to the user id.
  • Subscriptions: set metadata.distinct_id, in Checkout as subscription_data.metadata.distinct_id.

In the website's Settings → Revenue, copy the webhook URL into Stripe (Developers → Webhooks) with the events checkout.session.completed, invoice.paid, charge.refunded, refund.created and refund.updated, and paste the endpoint's signing secret. Only the amount, currency and time are kept, never the rest of Stripe's payload.

From any other payment system, send revenue from your server with an API key:

bash
curl -X POST https://analytics.example.com/api/websites/YOUR_SITE_ID/revenue \
  -H "Authorization: Bearer oat_…" \
  -H "Content-Type: application/json" \
  -d '{"distinct_id":"user-42","external_id":"sale_1001","kind":"payment","amount_cents":4900,"currency":"eur"}'
Field Meaning
external_id Your id for the payment or refund. Sending it again is ignored.
kind payment or refund.
amount_cents The amount in the currency's smallest unit, never negative. Refunds are subtracted.
currency ISO 4217 code, such as eur.
distinct_id Optional user id, as given to oxidt.identify.
occurred_at Optional RFC 3339 time. Defaults to now.

The response is 201 when stored and 200 when that external_id was already stored. While identification is off, revenue is stored without the user id.