# API keys
Source: https://docs.datalyr.com/account/api-keys
Generate and rotate workspace keys safely.
Open **Settings → API** to manage two workspace-scoped keys.
## Choose the right key
* **Agent key** (`dk_agent_…`): for AI Chat and services reading from the public `/v1` API. Hosted MCP connections use OAuth and do not reveal this key to the client.
* **Write key** (`dk_…`): for server SDKs and supported server-side write flows.
These keys are secrets. Do not put either one in browser code. Client-side Web SDK setup uses the public workspace ID instead. A write key cannot authenticate a `/v1` read request.
## Generate a key
1. Find the key type you need.
2. Select **Generate key**.
3. Confirm the action.
4. Copy the full value from the one-time dialog.
5. Store it in an environment variable or secret manager.
Datalyr only shows the full value once. After closing the dialog, the page displays a masked preview.
## Rotate a key
Rotation invalidates the current key immediately.
1. Identify every service using the current key.
2. Select **Regenerate** and confirm.
3. Copy the new value before closing the dialog.
4. Update every dependent environment.
5. deploy or restart those services.
6. Verify one authenticated request.
There is no overlap period between old and new keys, so plan rotation when a brief coordinated update is safe.
## If a key is exposed
Regenerate it immediately, update dependents, and review relevant service logs for unexpected use. Never send a full key to support; share only its prefix and masked ending when identifying which credential is involved.
Keys belong to the active workspace. A valid key from another workspace will not return or write the data you expected here.
# Plans and billing
Source: https://docs.datalyr.com/account/billing
Review your subscription, payment details, invoices, and billing status.
Open **Settings → Billing** to see the current plan, subscription status, cycle end, and usage. This page remains available when a subscription needs payment so the owner can recover it.
## Manage billing
Only the workspace owner can open the billing portal. Select **Manage billing** to handle the available subscription, payment-method, and invoice actions.
If you are not the owner, Datalyr shows the plan but tells you that only the owner can manage billing.
## Understand the status
* **Trialing:** the trial is active; the page shows the days remaining.
* **Active:** the subscription is current.
* **Past due or canceled:** open billing and resolve the payment or subscription state before expecting all paid surfaces to remain available.
The exact actions shown in the portal depend on the workspace's billing provider and current subscription.
## Shopify-billed workspaces
A workspace first billed through Shopify continues to use Shopify billing. Datalyr directs subscription management to Shopify rather than the standard billing portal.
If the app was uninstalled, reinstall it from the Shopify App Store. If the Shopify subscription was canceled, resume it from Shopify admin. Changing the subscription outside the correct provider will not repair the existing workspace state.
## Before changing a plan
Review **This cycle** usage for both events and postbacks. Plan changes affect limits and billing; they do not delete previously collected workspace data.
After a change, return to **Settings → Billing** and confirm the new plan or status. Shopify updates may return with a **Plan updated** confirmation.
Canceling a subscription and deleting a workspace are different actions. Cancellation controls billing. Workspace deletion permanently removes the workspace and its data.
# Delete a workspace
Source: https://docs.datalyr.com/account/delete-account
Permanently remove one Datalyr workspace and its data.
Workspace deletion is permanent. It removes events, integrations, attribution rules, and team membership tied to the workspace. Member user accounts are preserved.
Only the workspace owner can delete it.
## Before deleting
1. Confirm the workspace switcher shows the workspace you intend to remove.
2. Export anything your team must retain.
3. Record any configuration you may need to rebuild elsewhere.
4. Move or disable dependent API keys, SDKs, webhooks, and conversion rules.
5. Cancel or manage billing separately when required by the billing provider.
Deleting a workspace does not remove installed code from your website or app. Remove the Datalyr installation afterward so it does not keep trying to send data to a deleted destination.
## Delete the workspace
1. Open **Settings → Danger zone**.
2. Select **Delete workspace**.
3. Read the impact shown in the confirmation dialog.
4. Type the workspace name exactly.
5. Optionally add a reason.
6. Confirm **Delete workspace**.
After deletion, the workspace name becomes available and the team loses access to that workspace.
## Cancellation is different
Canceling a plan stops or changes the subscription according to the billing provider. It does not mean the workspace and its data were deleted. Conversely, do not assume workspace deletion handles every external subscription or installed app. Review **Settings → Billing** and the provider that bills the workspace.
If you only need to remove a teammate, disconnect a source, or stop one conversion rule, use that narrower action instead.
# Domains
Source: https://docs.datalyr.com/account/domains
Manage domains used by tracking links and supported first-party tracking.
Open **Settings → Domains** to manage the domains associated with the current workspace.
## Add a domain
1. Enter the hostname without a protocol or path.
2. Create the DNS record shown by Datalyr.
3. Wait for DNS propagation.
4. Refresh the domain status until it verifies.
5. Set the verified domain as the default when appropriate.
A verified domain can be used by supported tracking links and first-party tracking flows. The primary domain in **Settings → General** identifies the workspace's main website; it is not a substitute for completing domain verification here.
## Before removing a domain
Check active tracking links and installed scripts that use it. Removing the domain can stop those links or installs from working.
See [First-party tracking](/advanced/first-party-tracking) for implementation guidance.
# Account and billing
Source: https://docs.datalyr.com/account/index
Manage the workspace your team is currently using.
Datalyr settings are workspace-specific. Check the active workspace before changing its name, members, subscription, or keys.
## General
Use **Settings → General** for the workspace name, primary domain, favicon, timezone, and public workspace ID. The workspace ID is safe for supported client-side installation; secret API keys are managed elsewhere.
## Team
Use **Settings → Team** to invite admins or members, resend pending invitations, change roles, transfer ownership, and remove access. Owners have destructive and billing authority; members are read-only.
## Billing and usage
Use **Settings → Billing** for the current plan, subscription status, payment and invoice portal, and current-cycle event and postback usage. Only the owner can manage billing. Shopify-billed workspaces manage their subscription through Shopify.
## API keys
Use **Settings → API** for Agent and Write keys. Full keys appear only once after generation or rotation. Store them in a secret manager and never expose them in browser code.
## Danger zone
Workspace deletion permanently removes the workspace's events, integrations, rules, and memberships. It is owner-only and separate from subscription cancellation.
If an action is unavailable, first check your workspace role. The interface hides or disables owner- and admin-only controls for members.
# Team members
Source: https://docs.datalyr.com/account/team-members
Invite teammates, set roles, and remove workspace access.
Open **Settings → Team** to manage access to the current workspace. Never share one person's login.
## Roles
* **Owner:** full control, including billing, roles, ownership transfer, and workspace deletion.
* **Admin:** can edit settings, billing, and tracking.
* **Member:** read-only access to workspace data.
Only one person should need ownership for routine work. Grant the lowest role that lets someone do their job.
## Invite someone
1. Select **Invite member**.
2. Enter their email address.
3. Choose **Admin** or **Member**.
4. Send the invitation.
Owners and admins can manage invitations. Pending invites show separately and can be resent or revoked. Invitations expire, so resend an old invite instead of asking the recipient to keep retrying an expired link.
## Change a role
Use the role menu beside a member. Owners can assign ownership; admins cannot edit the owner's role. Promoting another person to owner transfers full control to them and downgrades the current owner to admin, so confirm the email carefully.
## Remove access
Select the remove action beside the member and confirm it. You cannot remove yourself through another member's row, and the owner must transfer ownership before they can lose owner access.
Removing a person from a workspace does not delete their Datalyr account or data already collected by the workspace.
## Troubleshoot invitations
**The invite did not arrive:** verify the address, check spam or company filtering, then use **Resend**.
**The link expired:** resend the pending invitation to issue a current link.
**You cannot see invite controls:** your current role does not have permission. Ask a workspace admin or owner.
Review access whenever an employee, contractor, or agency relationship ends.
# Usage
Source: https://docs.datalyr.com/account/usage
Understand event and postback usage for the current billing cycle.
Open **Settings → Billing** and find **This cycle**. Datalyr tracks two balances:
* **Events:** billable activity collected by the workspace, including pageviews, custom events, and supported source activity such as orders or payments.
* **Postbacks:** conversions Datalyr sends to connected ad platforms.
The page shows used, included, and remaining amounts. Billing data can lag ingestion by about five minutes, so a brand-new test may not change the total immediately.
## Investigate unexpected growth
1. Confirm you are viewing the correct workspace and billing cycle.
2. Open **Events** and group recent activity by event name and source.
3. Look for an event firing more often than the customer action it represents.
4. Review enabled conversion rules if postbacks are growing unexpectedly.
5. Check recent deployments and newly connected sources.
Common causes include page tracking mounted twice, a manual event called inside a repeated render, both client and server events sent without a shared idempotency ID, or a conversion rule that matches a broad event.
## Near or over the limit
Datalyr shows a warning as usage approaches the plan allowance. Current plans do not cut off collection at the limit; overage is billed according to the active plan. Review the current pricing and billing portal for the terms that apply to your workspace.
Do not delete tracking just to stop a short spike before finding its cause. First disable the specific duplicate event or overly broad conversion rule, then verify the rate returns to normal.
# Workspace settings
Source: https://docs.datalyr.com/account/workspace-settings
Manage the name, domain, favicon, timezone, and workspace ID.
Workspace settings apply only to the workspace currently selected in Datalyr.
## Update workspace details
Open **Settings → General**. You can review or update:
* **Workspace name:** shown to your team and in chart labels.
* **Primary domain:** the main website associated with the workspace.
* **Favicon:** the image used to identify the workspace.
* **Timezone:** the reporting timezone for the workspace.
* **Workspace ID:** the public identifier used by supported client-side setup flows.
Save the form after changing the name or primary domain. The current product shows timezone as a workspace value but does not allow it to be edited from this screen.
## Choose the primary domain
Use the domain customers actually visit. Enter the hostname without inventing a second workspace for `www` versus the root domain. If your journey crosses several domains, configure cross-domain tracking separately; the primary-domain field alone does not join those visits.
## Upload a favicon
Use a small square image that remains recognizable in a compact workspace switcher. If an upload fails, check the file type and size, then retry. Replacing a favicon can take a moment to appear everywhere because cached images may still be displayed.
## Copy the workspace ID
Use the copy control beside the public workspace ID. A typo or an ID from another workspace routes tracking to the wrong place. Before deploying, compare the ID in your installation with **Settings → General**.
## After a change
1. Reload Datalyr and confirm the intended workspace is active.
2. Open a familiar report and confirm labels still make sense.
3. If you changed the primary domain, test a new visit from that domain.
Changing a label does not rewrite historical events. It changes how the workspace is presented going forward.
# App campaigns
Source: https://docs.datalyr.com/advanced/app-campaigns
Connect campaign clicks to app opens, identities, and mobile revenue.
Mobile attribution spans more than the app. A useful setup connects the campaign link, store or deep-link handoff, mobile SDK, known user, revenue provider, and conversion destination.
## Build the path
1. Install the iOS or React Native SDK and verify an app-open event.
2. Configure the platform attribution and deep-link requirements described in that SDK guide.
3. Create a tracking link and choose **App install**.
4. Add the App Store and Play Store destinations you support.
5. Preserve the campaign macros required by the ad platform.
6. Call `identify` when the app knows the customer.
7. Connect RevenueCat, Superwall, Stripe, or another supported revenue source.
For Snapchat app delivery, a conversion rule can optionally use the connected Snap App ID. Other destinations expose their own supported app assets.
## Test correctly
Use a real device and a controlled link. Test both a fresh install and an open of an existing app where relevant. Confirm:
* the link click or landing event;
* the app event and supported attribution context;
* the known user after signup or login;
* the trial, purchase, or subscription event;
* the conversion delivery result.
Simulator tests do not reproduce every store, privacy, deep-link, or attribution framework behavior. Complete the final verification on a physical device.
Missing app attribution is commonly caused by stripped campaign parameters, an unhandled deep link, identity established after the revenue event, an offline queue that has not flushed, or platform privacy limitations.
# Conversion delivery
Source: https://docs.datalyr.com/advanced/conversion-delivery
Control which business events are sent to connected ad platforms.
Conversion delivery starts with a rule. The rule listens for a source event, creates a Datalyr conversion, enriches it with available first-party context, and sends the mapped event to one destination.
## Create a safe rule
1. Connect the destination under **Sources** and select the intended account asset.
2. Produce a real test source event and inspect it in **Events**.
3. Open **Conversions → Manage rules** and create a rule.
4. Choose the source, exact event name, destination platform, account asset, and platform event.
5. Map value from a numeric event field or use a static value; set the correct currency.
6. Add only destination parameters you can populate reliably.
7. Enable the rule and send one controlled test.
Google, Meta, TikTok, Snapchat, OpenAI, and mobile attribution destinations can expose different assets and fields. The rule editor only shows options supported by the selected destination and active connection.
## Verify both stages
Open the source row in **Events**, then the resulting row in **Conversions**. Finally, use the destination's test events or diagnostics to confirm acceptance. A successful Datalyr conversion does not guarantee the destination accepted or reported it.
## Prevent duplicates
* Do not run a second server-side sender for the same event unless deduplication is configured and tested.
* Use stable transaction or event IDs where the integration supports them.
* Check for two enabled rules with the same source, event, and destination.
* Do not retry by creating a new business event with a new ID.
Changing an enabled rule changes future delivery. It does not rewrite historical conversions in Datalyr or the destination.
# Cross-domain tracking
Source: https://docs.datalyr.com/advanced/cross-domain-tracking
Preserve supported attribution across websites and checkout domains.
Cross-domain tracking matters when a journey leaves one domain before conversion—for example, a marketing site sending a customer to a separate app or checkout.
## Map the journey first
Write down every owned domain, third-party checkout, redirect, and mobile handoff. Mark where campaign context is captured, where the user becomes known, and where revenue is created.
## Supported setup
1. Install Datalyr for the same workspace on each domain you control.
2. Use consistent campaign parameters on the first landing page.
3. Identify the customer with the same stable application ID wherever it is known.
4. For CheckoutChamp, add the checkout hosts under **Settings → Identity & Attribution**.
5. For Shopify guest checkout, use **Shopify cart attribution** when appropriate.
6. Use tracking links or documented platform bridges for web-to-app handoffs.
Do not invent a URL parameter containing a raw visitor or user ID. Arbitrary identity decoration can leak identifiers through browser history, analytics, logs, and referrer headers.
## Test end to end
Start in a private window with recognizable UTMs, cross each domain once, and complete a test conversion. Confirm the initial event, the known user journey, the revenue event, and the conversion record.
Third-party domains you cannot instrument may break browser continuity. A stable known-user identity or supported checkout integration can still connect the server-side conversion, but only when the required context was preserved earlier.
# Custom events
Source: https://docs.datalyr.com/advanced/custom-events
Track actions that matter to your product or funnel.
Use a custom event when the SDK cannot infer an important action automatically: a signup, lead submission, trial start, upgrade, or feature milestone.
## Design the event
Give each action a short, stable name. Use lowercase names such as `signup_completed` or `demo_booked`. Put variation in properties instead of creating dozens of event names.
```js theme={null}
datalyr.track("signup_completed", {
plan: "pro",
billing_period: "annual"
})
```
For a purchase-like event, send numeric value and an ISO currency when supported by the SDK and your conversion rule.
```js theme={null}
datalyr.track("order_completed", {
order_id: "ord_4821",
value: 79,
currency: "USD"
})
```
Use the exact method and options from the relevant **SDK Reference**. Server and mobile SDKs can also support original timestamps or idempotency values for delayed and retryable events.
## Verify it
1. Deploy to a test environment.
2. Perform the action once with a known test user.
3. Find the event in **Events**.
4. Confirm its name, identity, timestamp, and required properties.
5. If it drives a destination conversion, create the rule only after the source event is correct.
## Keep the schema clean
* Never put IDs or dynamic values in the event name.
* Keep property types consistent; do not alternate between `79` and `"79"`.
* Use a stable order or transaction ID to prevent accidental duplicate business events.
* Document required properties in your application repository.
Do not include passwords, tokens, complete payment details, or regulated personal data in custom properties.
# Filters
Source: https://docs.datalyr.com/advanced/filters
Allow sites, block internal traffic, skip pages, and normalize dynamic paths.
Filters trim unwanted data before it reaches your workspace. Filtered events are dropped before billing.
Open **Settings → Filters**.
## Additional websites
Add every separate domain or exact subdomain where this workspace's Web SDK runs. The primary domain and its apex/`www` pair are included automatically. Wildcards such as `*.example.com` include all subdomains.
## Blocked IPs
Add individual IP addresses or CIDR ranges to remove office, agency, QA, or other internal traffic.
```text theme={null}
203.0.113.42
10.0.0.0/24
```
## Blocked pages
Skip page paths that should not be collected:
```text theme={null}
/admin
/staging/*
```
## Masked pages
Collapse dynamic paths into one reportable pattern:
```text theme={null}
/orders/:id
/users/:userId/profile
```
This makes `/orders/abc` and `/orders/xyz` aggregate as `/orders/:id` without blocking the page views.
## Verify changes
Test one included and one excluded request after saving. Filters apply to new events; they do not rewrite historical data.
A broad hostname, IP range, or wildcard can remove legitimate customer activity. Start narrow and verify each rule.
# First-party tracking
Source: https://docs.datalyr.com/advanced/first-party-tracking
Serve supported tracking and campaign links from your own subdomain.
A first-party tracking domain uses a subdomain you control, such as `go.example.com`, for the Datalyr install path and supported tracking-link traffic. It can reduce blocking and keep links on your brand.
## Add a domain
1. Open **Settings → Domains**.
2. Add a dedicated subdomain. Datalyr suggests `go.` because tracker-like hostnames are more likely to be blocked.
3. Copy the DNS records shown for that domain.
4. Add them at your DNS provider exactly as displayed.
5. Return to Datalyr and select **Verify**.
The domain moves through Pending, Verifying, Active, or Failed. DNS changes can take time. Do not remove the shared install while verification is incomplete.
Once active, Datalyr can use the preferred active domain in the install snippet, and it becomes available when creating tracking links. If Shopify is connected, the domain card can offer **Route Shopify** to repoint the supported Web Pixel flow.
## Verify the result
1. Copy the install snippet from **Settings → Tracking** after activation.
2. Load a tracked page in a private window.
3. Confirm the script request uses your domain.
4. Find the pageview in **Live** or **Events**.
5. Create and test one link hosted on the domain.
Removing a live domain can affect install snippets, redirect links, and a routed Shopify pixel. Move those flows first and follow the removal warning shown in Datalyr.
First-party delivery does not override consent, GPC, DNT, or other privacy controls.
# Health and wellness redaction
Source: https://docs.datalyr.com/advanced/health-wellness-redaction
Strip sensitive product context from outgoing ad-platform conversions.
The Health & Wellness filter removes sensitive-category context before conversion events are sent to Meta, TikTok, OpenAI, and Google.
Use it for supplements, vitamins, wellness products, telehealth, pharmacy, or other health-adjacent catalogs whose product names or URLs can trigger platform restrictions.
## Turn it on
1. Connect at least one supported conversion destination in **Sources**.
2. Open **Settings → Privacy & redaction**.
3. Turn on **Strip health-vertical fields**.
4. Send a controlled test conversion.
The switch is disabled until a supported CAPI connection exists. The change applies to new outgoing conversion events.
## What is removed
The filter strips or scrubs sensitive context including:
* `content_name` and `content_category`
* Product or content fields containing health-related keywords
* Sensitive values inside product-content arrays
* URL paths containing health terms
When a URL is scrubbed, Datalyr preserves the origin and replaces the sensitive path.
## What stays
Datalyr preserves the matching and measurement signals used for attribution:
* Hashed email and phone
* Supported click IDs
* External or customer ID
* Order ID
* Value and currency
* IP address and user agent when allowed
## Verify the payload
1. Use a recent purchase containing a health-related product name.
2. Send it through the conversion rule's supported test flow.
3. Open the destination platform's test-event or diagnostics view.
4. Confirm sensitive product fields are absent.
5. Confirm value, currency, order ID, and permitted matching fields remain.
Redaction uses conservative keyword matching. A non-health product containing a matched term can also be redacted. Review test payloads before relying on the setting in production.
The setting applies across all supported conversion destinations rather than one rule at a time.
# Identity
Source: https://docs.datalyr.com/advanced/identity
Connect anonymous activity to known customers without mixing accounts.
Datalyr starts with an anonymous visitor. When your application knows who that visitor is, `identify` attaches a stable customer ID so later events and eligible journey context can be joined.
## Identify at a trusted moment
Call `identify` after signup, login, or another verified identity moment. Prefer your immutable internal user ID over an email address.
```js theme={null}
datalyr.identify("usr_4821", {
email: "customer@example.com",
plan: "pro"
})
```
Email and plan are traits. `usr_4821` is the primary ID. If an email changes, the user remains the same.
Call the SDK's reset or logout method when someone logs out or switches accounts. This is essential on shared devices.
## Automatic identity settings
Under **Settings → Identity & Attribution**, Datalyr can expose these web controls:
* **Auto Identify** captures email from supported form submissions and Shopify flows.
* **Shopify cart attribution** stamps supported visitor and click context into the cart for guest checkout attribution.
* **CheckoutChamp domains** lists checkout hosts that should participate in the supported bridge.
* **Honor Global Privacy Control** is on by default.
* **Honor Do Not Track** is off by default.
* **Strict privacy mode** disables auto-identify and applies conservative collection.
Sensitive workspaces use safer defaults. Review the effective label shown by each setting rather than assuming the default.
## Verify identity
1. Start a private session and browse anonymously.
2. Sign up or log in.
3. Open **Users** and search for the stable ID.
4. Confirm the earlier visit and later known activity form the expected journey.
5. Log out, then confirm a new account does not inherit the previous identity.
Use `alias` only when you know two IDs belong to the same person. Never join identities based only on IP, device, name, or a similar attribute.
# Advanced
Source: https://docs.datalyr.com/advanced/index
Configure custom collection, identity, delivery, and privacy.
Use these guides after the standard installation and revenue source are working.
| Guide | Use it when |
| ------------------------- | -------------------------------------------------------------- |
| **Custom events** | Your product has an action Datalyr cannot infer automatically. |
| **Identity** | Anonymous activity must connect to a known customer. |
| **Attribution** | You need to verify how campaign context reached revenue. |
| **Conversion delivery** | A business event should be sent to an ad platform. |
| **First-party tracking** | You want supported tracking on your own subdomain. |
| **Cross-domain tracking** | The journey moves between sites or checkouts. |
| **Pixels and scripts** | Datalyr should load a supported browser tag. |
| **App campaigns** | A campaign moves from web or ad click into a mobile app. |
| **Privacy and redaction** | Collection or delivery must follow stricter controls. |
Change one part of the setup at a time and complete a controlled test. Identity, attribution, and conversion rules affect future data across the workspace.
# Pixels and scripts
Source: https://docs.datalyr.com/advanced/pixels-and-scripts
Load supported marketing tags through the Datalyr container.
The Datalyr container can manage a Meta Pixel, Google Tag, TikTok Pixel, external script URL, or inline JavaScript after the Datalyr web install is present.
## Add a script
1. Verify the web SDK in **Live** or **Events**.
2. Open **Settings → Container**.
3. Select **Add script**.
4. Give it a recognizable name and choose its type.
5. Enter the pixel ID, tag ID, external HTTPS URL, or inline code.
6. Save it, then load a test page.
Each saved script can be enabled, edited, or removed. The page also surfaces recorded error counts and the latest error details when execution fails.
## Avoid duplicate tags
Before enabling a pixel, inspect your site theme, tag manager, checkout, and other apps. Loading the same base tag twice can duplicate browser events even when server-side conversion delivery is correct.
Verify with the browser's network tools and the destination's pixel helper. One page load should initialize each intended base tag once. Then perform one test action and confirm one corresponding browser event.
## Use custom scripts carefully
External and inline scripts execute on your site. Review their source, pin trusted URLs where possible, and test them outside production first. A broken script can affect page performance or behavior.
Container delivery does not grant consent. Only enable advertising or analytics scripts when your consent policy permits them.
# Privacy and redaction
Source: https://docs.datalyr.com/advanced/privacy
Control automatic identity, browser privacy signals, and sensitive conversion data.
Privacy controls change what Datalyr collects or sends. Configure them before production traffic, then test the opted-in and opted-out paths separately.
## Browser controls
Open **Settings → Identity & Attribution** to review:
* **Honor Global Privacy Control** — enabled by default and suppresses tracking when the browser sends GPC.
* **Honor Do Not Track** — disabled by default because browser support is legacy; enable it for a stricter posture.
* **Strict privacy mode** — disables Auto Identify and applies conservative collection.
* **Auto Identify** — captures email only in supported flows and should be disabled where your policy does not allow it.
Sensitive or health-related workspaces use safer effective defaults. The settings page marks defaults separately from explicit choices.
## Conversion redaction
Under **Settings → Privacy & redaction**, a workspace can enable the health-vertical filter. The resulting redaction policy applies across supported conversion destinations: Meta, TikTok, Google, and OpenAI. The control is unavailable until a supported destination is connected.
Redaction can remove or limit sensitive URL and keyword context before delivery. It is not permission to collect sensitive data in the first place.
See [Health and wellness redaction](/advanced/health-wellness-redaction) for the exact behavior and verification flow.
## Test your posture
1. Test normal consent and confirm only expected fields appear in **Events**.
2. Enable GPC in a test browser and confirm tracking is suppressed as intended.
3. Test your consent denial path before any optional script loads.
4. Log out or switch accounts and confirm identity resets.
5. Send a test conversion and inspect the destination payload diagnostics for redaction.
Never send passwords, access tokens, complete payment details, medical details, or other regulated data in URLs, event names, or arbitrary properties. Datalyr settings do not replace legal review or your consent interface.
# Get devices
Source: https://docs.datalyr.com/api-reference/analytics/get-devices
/api-reference/read-api.yaml get /devices
# Get locations
Source: https://docs.datalyr.com/api-reference/analytics/get-locations
/api-reference/read-api.yaml get /locations
# Get overview
Source: https://docs.datalyr.com/api-reference/analytics/get-overview
/api-reference/read-api.yaml get /overview
# Get realtime activity
Source: https://docs.datalyr.com/api-reference/analytics/get-realtime-activity
/api-reference/read-api.yaml get /realtime
# Get traffic
Source: https://docs.datalyr.com/api-reference/analytics/get-traffic
/api-reference/read-api.yaml get /traffic
# Get ad performance
Source: https://docs.datalyr.com/api-reference/attribution-and-revenue/get-ad-performance
/api-reference/read-api.yaml get /ads
# Get attribution
Source: https://docs.datalyr.com/api-reference/attribution-and-revenue/get-attribution
/api-reference/read-api.yaml get /attribution
# Get certified commerce metrics
Source: https://docs.datalyr.com/api-reference/attribution-and-revenue/get-certified-commerce-metrics
/api-reference/read-api.yaml get /commerce-metrics
Returns policy-governed revenue, ad spend, profit, margin, ROAS, MER, and completeness statuses.
# Get revenue
Source: https://docs.datalyr.com/api-reference/attribution-and-revenue/get-revenue
/api-reference/read-api.yaml get /revenue
# Get trackable link tags
Source: https://docs.datalyr.com/api-reference/attribution-and-revenue/get-trackable-link-tags
/api-reference/read-api.yaml get /tags
# Authentication
Source: https://docs.datalyr.com/api-reference/authentication
Authenticate read requests with a Datalyr Agent key.
Create or copy your **Agent key** from **Settings → API** in Datalyr.
Send your key as a bearer token:
```bash theme={null}
curl "https://api.datalyr.com/v1/workspace" \
--header "Authorization: Bearer dk_agent_your_api_key"
```
Only keys beginning with `dk_agent_` can read from `/v1`. A write key beginning with `dk_` is not a read credential and is rejected by these endpoints.
Keep Agent keys on your server. Do not include them in public source code or expose them in a browser bundle. To use Datalyr from Claude or Codex without handling a key, [connect the hosted MCP server](/datalyr-mcp).
# Errors and limits
Source: https://docs.datalyr.com/api-reference/errors-and-limits
Handle API errors and request limits.
Errors use a JSON response with an `error` field.
```json theme={null}
{
"error": "Invalid or missing Agent API key"
}
```
## Request limits
The API allows 100 requests per minute for each workspace. A request over the limit returns `429`.
## Status codes
| Status | Meaning |
| ------ | ------------------------------------------------------------------------ |
| `400` | The request is missing a required value or contains invalid JSON. |
| `401` | The Agent key is missing or invalid. Public write keys are not accepted. |
| `404` | The requested resource was not found. |
| `405` | The endpoint does not support the request method. |
| `429` | The request limit was exceeded. |
# Get user
Source: https://docs.datalyr.com/api-reference/events-and-users/get-user
/api-reference/read-api.yaml get /users/{userId}
# List event names
Source: https://docs.datalyr.com/api-reference/events-and-users/list-event-names
/api-reference/read-api.yaml get /event-names
# List events
Source: https://docs.datalyr.com/api-reference/events-and-users/list-events
/api-reference/read-api.yaml get /events
# List users
Source: https://docs.datalyr.com/api-reference/events-and-users/list-users
/api-reference/read-api.yaml get /users
# API Reference
Source: https://docs.datalyr.com/api-reference/index
Read your Datalyr data with the public API.
Use the Datalyr API to read analytics and workspace data.
## Base URLs
```text theme={null}
https://api.datalyr.com/v1
```
Query analytics, attribution, events, revenue, and workspace data.
This reference only covers public endpoints at `api.datalyr.com/v1`. Dashboard and internal service routes are not public APIs.
# Get usage
Source: https://docs.datalyr.com/api-reference/workspace/get-usage
/api-reference/read-api.yaml get /usage
# Get workspace
Source: https://docs.datalyr.com/api-reference/workspace/get-workspace
/api-reference/read-api.yaml get /workspace
# Attribution
Source: https://docs.datalyr.com/attribution/index
Understand how campaign context reaches a customer and conversion.
Attribution connects a conversion to the marketing context captured earlier in the journey. Datalyr uses available first-party context—such as campaign parameters, supported click IDs, tracking links, visitor identity, and connected revenue events—to build that connection.
## What has to work
```text theme={null}
Campaign visit → context captured → identity preserved → conversion received
```
If one stage is missing, the conversion can still exist without a useful campaign assignment.
## Verify an attributed journey
1. Create a controlled campaign or tracking link with recognizable UTMs.
2. Open it in a private browser.
3. Confirm the visit in **Live** or **Events**.
4. Complete the identity and conversion steps.
5. Open the customer in **Users** and follow the touchpoints.
6. Open **Conversions** to inspect the rule match and delivery separately.
## Why platforms disagree
Ad platforms can use their own click and view windows, models, timezones, and modeled conversions. Revenue systems usually report the transaction without assigning marketing credit. Datalyr's first-party view will not always equal either one.
Before comparing totals, align:
* the exact date range and timezone;
* conversion event definition;
* gross versus net revenue;
* currency handling;
* attribution window and model;
* click-through versus view-through inclusion.
Attribution is evidence from the context available to Datalyr. It cannot recreate a click identifier, campaign parameter, or identity link that was never collected.
## Improve missing attribution
Use consistent UTMs, install tracking on every owned step, identify customers at a trusted moment, preserve identity across checkout where supported, and connect the system that records revenue. A first-party domain can also reduce blocking, but it does not bypass consent or browser privacy choices.
# Connect Claude or Codex
Source: https://docs.datalyr.com/datalyr-mcp
Use your Datalyr data from Claude, Codex, and other remote MCP clients.
Datalyr provides a hosted, read-only MCP server. Connect it once with your Datalyr account, then ask your AI client about analytics, customers, attribution, ads, revenue, profit, and usage.
```text theme={null}
https://api.datalyr.com/mcp
```
You do not need an Anthropic or OpenAI API key. Your AI subscription and Datalyr account stay separate, and Datalyr never receives your Claude or Codex subscription credentials.
## Connect Claude
For an individual Claude account:
1. Open **Customize → Connectors** in Claude.
2. Select **+ → Add custom connector**.
3. Enter `Datalyr` as the name and `https://api.datalyr.com/mcp` as the remote MCP URL.
4. Select **Add**, then **Connect**.
5. Sign in to Datalyr and allow read-only access.
On Claude Team or Enterprise, an Owner first adds the URL under **Organization settings → Connectors**. Each member then opens **Customize → Connectors** and connects their own Datalyr account.
Start a new conversation and ask: `List my Datalyr workspaces.`
## Connect Codex
Add the Streamable HTTP server from a terminal:
```bash theme={null}
codex mcp add datalyr --url https://api.datalyr.com/mcp
codex mcp login datalyr --scopes datalyr:read
```
Complete the Datalyr sign-in and consent page in your browser. The configuration is then available to Codex surfaces that share your MCP configuration.
## What the connection can read
The server can list workspaces you belong to and read:
* overview, traffic, devices, locations, and realtime activity
* events, event names, users, and user journeys
* campaign attribution and ad performance
* revenue, certified commerce metrics, tracking-link tags, and usage
If your account has more than one workspace, the client first lists them and passes the selected workspace ID to later tools.
MCP results can contain customer, campaign, and financial data. Only connect AI clients and organizations you trust. AI-generated conclusions can be wrong; verify high-impact decisions against the corresponding Datalyr report.
## Access and key safety
The connection uses OAuth. Claude or Codex receives a short-lived, read-only token, not the workspace Agent key. The MCP server checks your current workspace membership on every tool call.
The connection cannot change tracking, settings, sources, conversion rules, team membership, or billing.
## Disconnect or troubleshoot
Remove Datalyr from your client's connector or MCP settings to stop that client from requesting new data.
If authentication fails, remove the connection and add it again. Make sure your Datalyr account still belongs to the workspace you are trying to query.
If an analytics request fails, ask the client to call `list_workspaces` again and include the returned workspace ID. Date-based tools accept a complete start and end time, or neither; omitting both uses the last 30 days.
# Choose your setup
Source: https://docs.datalyr.com/getting-started/choose-your-setup
Pick the shortest setup path for your business.
Choose the path that matches where customers visit and pay you.
Use the web tracking script or Web SDK.
Use the Shopify setup for storefront activity and orders.
Track the website, then connect Stripe revenue.
Use the iOS or React Native SDK and connect mobile revenue.
## What every setup needs
Every complete setup has three parts:
* A customer activity source, such as your website or app
* A revenue source, such as Shopify, Stripe, RevenueCat, or Superwall
* The ad platforms you want to measure
Start with the first two. Ad reporting is only useful after customer activity and revenue are arriving correctly.
# Install web tracking
Source: https://docs.datalyr.com/getting-started/install-web-tracking
Add Datalyr to every page and send your first page view.
The web snippet is the fastest way to track a website. It records page views and campaign context without requiring custom event code.
## Before you start
You need permission to publish the site and your Datalyr workspace ID. In Datalyr, open **Settings → Install**. New workspaces also show the same snippet on the dashboard until the first event arrives.
## Install the snippet
Open **Settings → Install** and copy the snippet shown for your workspace. The workspace ID is already filled in.
Add it inside the `` of every page, before the closing `` tag. Put it in the shared site template when possible.
A local or draft change cannot send production visits. Deploy or publish it before testing.
Use a private window so the test starts with a clean visitor and session.
```html theme={null}
```
Use the exact workspace ID shown in Datalyr. Do not reuse an ID from another workspace.
## What starts automatically
The snippet records page views, sessions, anonymous visitors, URLs, referrers, UTM parameters, supported ad click IDs, and browser context. It also tracks route changes in single-page applications.
Automatic tracking does not know who a visitor is or which product action matters to you. Add [`identify`](/sdk-reference/web#identify-a-user) after sign-in and custom events for actions such as signup, lead submission, or checkout.
## Install with npm
Use the package when your application owns its JavaScript lifecycle.
```bash theme={null}
npm install @datalyr/web
```
```ts theme={null}
import datalyr from '@datalyr/web'
datalyr.init({ workspaceId: 'YOUR_WORKSPACE_ID' })
await datalyr.ready()
```
Choose the snippet or npm package. Never initialize both on the same page.
## Common framework placement
| Platform | Where to install |
| ----------------- | ------------------------------------------------------------- |
| Next.js | Root layout or a client-side analytics component loaded once |
| React or Vue SPA | Application entry point, initialized once |
| WordPress | Site-wide header through the theme or a header-injection tool |
| Webflow or Framer | Global custom code in the site head |
| Custom HTML | Shared `` template on every page |
Do not place the snippet only on the confirmation page. Datalyr needs the landing visit to connect campaign context to the later conversion.
## Verify the install
Open **Events** and look for a recent `pageview` with the URL you visited. If it is missing, confirm the published HTML contains `dl.js`, the workspace ID is correct, and an ad blocker or consent setting did not block analytics.
Seeing `dl.js` in page source only proves the tag was published. The setup is complete only when the event appears in Datalyr.
Next, [run the full verification checklist](/getting-started/verify-your-setup).
# Verify your setup
Source: https://docs.datalyr.com/getting-started/verify-your-setup
Test tracking, attribution, identity, and revenue before sending paid traffic.
Run this check on the published site. A correct install should preserve one journey from the landing page through identification and conversion.
## 1. Test a clean visit
Open a private window and visit a page with test campaign parameters:
```text theme={null}
https://example.com/?utm_source=docs_test&utm_medium=paid&utm_campaign=setup_check
```
Return to Datalyr and open **Events**. Find the newest `pageview` and confirm:
* The URL and path match the page you opened.
* `utm_source` is `docs_test`.
* `utm_medium` is `paid`.
* `utm_campaign` is `setup_check`.
* An anonymous or visitor ID is present.
Navigate to a second page. Its page view should use the same visitor and session.
## 2. Test identity
If users sign in, complete a sign-in in the same private window. Your application should identify the customer with a stable ID from your database.
```ts theme={null}
datalyr.identify('user_123', {
email: 'person@example.com',
name: 'Test Customer'
})
```
Confirm `$identify` appears in **Events** and the customer appears in **Users**. The earlier anonymous visit should remain part of that customer's journey.
Do not use an email address as the primary ID if your database has a stable user ID. Emails can change.
## 3. Test a product event
Trigger one action that matters to your funnel:
```ts theme={null}
datalyr.track('signup_completed', {
plan: 'starter',
source: 'verification'
})
```
Open the event and check its properties. Event names should be stable, lowercase, and descriptive. Avoid generating event names from button text or page titles.
## 4. Test revenue
After connecting a revenue source, use its sandbox or test flow when supported. Confirm the purchase or subscription appears with a transaction ID, amount, currency, customer identifier, and source.
Then open the customer in **Users**. The landing visit, identity event, product event, and revenue event should form one journey.
## If an event is missing
Check in this order:
1. The change was published to the URL you tested.
2. The page contains one Datalyr install, not zero or two.
3. The workspace ID matches **Settings → Install**.
4. Analytics consent was granted, if your site requires it.
5. The test browser is not blocking the request.
6. The browser console has no Datalyr initialization error.
Enable debug logging temporarily:
```html theme={null}
```
Remove `data-debug="true"` after testing.
## If the event exists but attribution is missing
Start a new private session with the test URL. Check that redirects preserve the query string and that no landing-page script removes campaign parameters before Datalyr loads. For cross-domain journeys, configure the domains before testing.
You are ready when the page view, campaign fields, identity, key product event, and test revenue all appear on the expected customer journey.
# What is Datalyr?
Source: https://docs.datalyr.com/index
See which marketing brings you customers and revenue.
Datalyr brings your customer activity, revenue, and ad spend together.
Use it to see where customers came from, what they did before converting, and which marketing created revenue.
## Start with your setup
Add Datalyr to a website or web app.
Connect your store, orders, and marketing.
Track installs, activity, subscriptions, and campaigns.
Connect website activity to subscriptions and revenue.
## How the pieces fit together
1. **Track customer activity.** Add Datalyr to your website or app.
2. **Connect revenue.** Add the source where customers pay you.
3. **Connect ad platforms.** Bring in spend and campaign data.
4. **Verify the data.** Confirm that visits, conversions, and revenue appear correctly.
You do not need to connect everything at once. Start with customer activity and revenue, verify both, then add ad platforms.
# Installation
Source: https://docs.datalyr.com/installation/index
Choose the install that matches where your customers interact with you.
Install Datalyr anywhere a customer can visit, sign up, or buy. Start with the surface that receives your paid traffic.
## Choose an install
| Your product | Install | What it captures |
| ------------------------------ | ----------------------------------------------------- | ---------------------------------------------------------------------- |
| Website or landing page | [Web tracking](/getting-started/install-web-tracking) | Visits, sessions, campaign parameters, click IDs, and web events |
| Shopify store | [Shopify](/installation/shopify) | Storefront behavior, checkout activity, customers, orders, and refunds |
| Native iOS app | [iOS SDK](/sdk-reference/ios) | App sessions, screens, identity, and app events |
| React Native or Expo app | [React Native SDK](/sdk-reference/react-native) | App sessions, screens, identity, and app events |
| Backend or serverless function | [Node.js SDK](/sdk-reference/node) | Trusted server events and user activity |
A mobile campaign with a web landing page needs both installs: the Web SDK on the landing page and the mobile SDK in the app.
## Before you start
You need a Datalyr workspace and access to publish changes to your site, store, or app. Use the same workspace ID across every install that belongs to the same business.
Do not install the script and the Web SDK on the same page. That sends the same automatic activity twice.
## The setup order
Add the web snippet or the correct SDK. Publish the change.
Open the published site or app and move through a short customer journey.
Open **Events** in Datalyr and inspect the newest event. Check its URL, source, identifiers, and campaign fields.
Connect the system that owns the payment after behavioral tracking works.
## What success looks like
Your setup is ready when a new visit appears in **Events**, campaign parameters survive navigation, and an identified customer or test purchase joins the same journey.
Test page views, campaign data, identity, and custom events.
Add the system that owns purchases or subscriptions.
# Install in a mobile app
Source: https://docs.datalyr.com/installation/mobile
Track app sessions, screens, users, and campaign journeys.
Mobile apps use a native SDK. Do not load the web snippet inside the app as a replacement for an SDK.
## Choose the SDK
* Use the [iOS SDK](/sdk-reference/ios) for native Swift apps.
* Use the [React Native SDK](/sdk-reference/react-native) for React Native and Expo.
* Add the [Web SDK](/getting-started/install-web-tracking) too when campaigns land on a website before the app store.
## Setup order
Follow the package-manager instructions in the SDK reference and use the workspace ID from **Settings → Install**.
Initialize near application startup, before tracking screens or product events. Do not initialize again on every view.
Send a screen event when the visible screen changes. React Native apps should use the documented React Navigation or Expo Router integration.
Use the same stable user ID used by your backend and billing provider.
Launch a development build, open a screen, identify a test user, and trigger one product event.
## What to verify
Open **Events** and confirm the app session, screen, identity, and custom event use the expected source and identifiers. Open **Users** and verify those events belong to one test customer.
If you use RevenueCat or Superwall, pass the Datalyr identity fields using the SDK helper documented for your platform. This is what lets subscription events join the app journey.
## Common failures
* **No events:** initialization did not run, the workspace ID is wrong, or the app was not rebuilt after installation.
* **Duplicate screens:** both automatic navigation tracking and manual screen tracking are enabled.
* **Revenue is unassigned:** the app user ID and billing-provider identity were never connected.
* **Only development works:** the production target is missing the package or initialization configuration.
Continue with the [mobile use case](/use-cases/mobile) for web-to-app attribution, subscriptions, and campaign setup.
# Install on Shopify
Source: https://docs.datalyr.com/installation/shopify
Connect orders and turn on storefront and checkout tracking.
The Shopify connection has two parts: the source imports commerce activity, and the storefront install captures the visit that caused it. Complete both.
## Before you start
You need access to the Shopify admin, permission to install apps, and your permanent `myshopify.com` domain. Use that domain even if customers visit a custom domain.
## Connect Shopify
In Datalyr, open **Sources**, find **Shopify**, and select **Connect**.
Enter `mystore` or `mystore.myshopify.com`. Datalyr redirects you to Shopify Admin.
Review the requested access and complete the Shopify authorization.
Back in Datalyr, select **Install pixel** if the Shopify Web Pixel is not already marked installed. This covers checkout activity that the theme cannot see.
Open the theme editor from the setup prompt. In **App embeds**, turn on **Datalyr**, select **Save**, then visit the storefront once.
Orders can import even when the App Embed is off. In that state, revenue exists but storefront visits, click IDs, and ad attribution are incomplete.
## What Shopify sends
The connection supports customers, checkouts, paid and fulfilled orders, cancellations, and refunds. The storefront install adds page views, visitor identity, campaign parameters, and click IDs. Datalyr uses those signals to join the order to the earlier visit.
## Verify the setup
1. Open the storefront in a private window with a test UTM URL.
2. Browse a product and begin checkout.
3. In **Events**, confirm a storefront `pageview` appears.
4. Use Shopify's supported test-payment flow to place an order.
5. Confirm the paid order has an order ID, amount, currency, and customer data.
6. Open the customer in **Users** and verify the storefront visit and order share a journey.
## Common failures
* **Store is connected but no storefront events:** turn on the Datalyr App Embed and save the theme.
* **Storefront works but checkout is missing:** return to the Shopify source and install the Web Pixel.
* **Shop domain is rejected:** use the permanent `myshopify.com` subdomain, without a protocol or path.
* **Orders appear without attribution:** test a new order after enabling the embed; historical orders cannot recreate a missing browser visit.
* **Duplicate page views:** remove any separately pasted Datalyr snippet from the Shopify theme when the App Embed owns storefront tracking.
Next, review [ecommerce revenue](/revenue/ecommerce) or follow the full [Shopify use case](/use-cases/shopify).
# Apple SKAdNetwork
Source: https://docs.datalyr.com/integrations/apple-skadnetwork
Configure SKAdNetwork postbacks for supported iOS campaigns.
Use the Apple SKAdNetwork source for privacy-preserving iOS campaign measurement.
## Connect
1. Open **Sources → Apple SKAdNetwork**.
2. Enter the iOS Bundle ID.
3. Copy the postback URL shown for the workspace.
4. Add the supported configuration to the app and campaign setup.
5. Initialize the iOS or React Native SDK with the appropriate conversion template when required.
Supported templates include ecommerce, gaming, and subscription flows.
## Verify
SKAdNetwork postbacks are delayed and privacy-governed, so they do not behave like live browser events. Confirm the Bundle ID and postback URL first, then inspect received SKAdNetwork activity after Apple's reporting window.
See the [iOS SDK](/sdk-reference/ios) or [React Native SDK](/sdk-reference/react-native) for conversion-value helpers.
# Google Ads
Source: https://docs.datalyr.com/integrations/google-ads
Connect a Google Ads customer account for reporting and conversions.
Connect Google Ads to see campaign cost and performance beside Datalyr revenue, then send eligible conversions back to Google.
## Before you connect
Sign in with a Google user that can access the final customer account. Manager account access is useful, but you still need to select the individual customer account whose campaigns you want in this workspace.
Have the customer ID ready if several accounts have similar names. Datalyr shows the account name, ID, currency, and status in the selection step.
## Connect Google Ads
1. Open **Sources**.
2. Find **Google Ads** and select **Connect**.
3. Complete Google authorization and approve the requested access.
4. Choose the final customer account—not the manager account used only to administer it.
5. Select **Set as primary**.
Datalyr starts a campaign-data sync after the primary account is saved.
Datalyr uses one primary Google Ads customer account per connection. To change it, disconnect and reconnect the source.
## Set up a conversion
Open **Conversions** and add a rule that matches a real Datalyr event. Choose Google Ads as the destination and select the supported conversion configuration shown in the editor.
For the cleanest test, use a unique event or transaction and preserve its original timestamp, value, currency, and available click or customer identifiers. Google decides whether an accepted conversion is eligible for attribution.
## Verify the connection
1. Confirm Google Ads is **Connected** in **Sources**.
2. Confirm the displayed primary account matches the customer ID you intended.
3. Open a report with a recent date range and verify known cost or click activity appears.
4. Trigger one event that matches an enabled conversion rule.
5. Check its delivery result in Datalyr before looking for it in Google Ads.
Campaign syncs and Google reporting are not instant. Avoid judging the connection from the current hour alone.
## Common problems
**No accounts appear**
The Google user cannot access an eligible customer account, or the wrong Google profile was authorized. Verify access in Google Ads, then reconnect.
**The manager account appears, but not the client account**
Confirm the client link is active and the authorizing user has direct or manager-level access to that customer.
**The source needs configuration**
Authorization succeeded, but no primary customer account was saved. Reopen the source and finish account selection.
**A conversion was accepted but is not in a campaign report**
Check for a usable click identifier, the conversion action and time, and Google’s own processing delay. Acceptance and attribution are separate stages.
# Integrations
Source: https://docs.datalyr.com/integrations/index
Connect revenue sources and ad platforms to your workspace.
Open **Sources** to connect the services that produce revenue or run campaigns. Each source belongs to one of two practical groups.
## Data sources
Data sources send customer and revenue activity to Datalyr. These include services such as Shopify, Stripe, RevenueCat, Superwall, Whop, and Checkout Champ. Some use authorization; others provide a workspace-specific webhook URL or ask for a secret.
After connecting a revenue source, complete any setup shown by its connection flow. For example, Shopify requires its theme app embed for storefront attribution, while Stripe needs Datalyr identity metadata attached to checkout or payment records.
## Ad platforms
Ad platforms pull campaign performance and can receive conversions selected in **Conversions**.
* **Meta, Google Ads, and TikTok:** authorize, then choose one primary ad account.
* **Snapchat:** authorize in Sources; enter the Pixel ID or App ID on each conversion rule.
* **OpenAI Ads:** enter and validate an API key and Pixel ID.
## A safe setup order
1. Install tracking and confirm a test event in **Events**.
2. Connect the source of truth for revenue.
3. Trace one real or test transaction into Datalyr.
4. Connect an ad platform and verify its primary account or destination asset.
5. Create one conversion rule.
6. Check one end-to-end delivery before adding more rules.
This order keeps failures easy to isolate. If the original event is missing, reconnecting an ad account will not fix it.
## Connection states
**Connected** means authorization or credentials are active. **Needs configuration** means authorization succeeded but a required step—usually primary account selection—was not completed. **Error** means the source needs attention. A deletion state means cleanup is still running; use the available retry action if it remains stuck.
Source cards can show recent activity. Treat this as a freshness signal, not a guarantee that every expected event or campaign has synced.
Always check the active workspace before connecting a source. Connections, events, rules, usage, and keys are workspace-specific.
# Meta Ads
Source: https://docs.datalyr.com/integrations/meta-ads
Connect one Meta ad account for reporting and conversion delivery.
Connect Meta to pull campaign performance into Datalyr and send matched conversions back to Meta.
## Before you connect
Use a Meta login that can access the ad account you want to use. If the account belongs to a client or another business, confirm that the login can see it in Meta Business settings before starting.
Know which ad account is correct. Datalyr asks you to choose one primary account after authorization. That account is used for both campaign data and conversion delivery.
## Connect Meta
1. Open **Sources**.
2. Find **Meta Ads** and select **Connect**.
3. Complete the Meta authorization window. Approve the requested access instead of removing individual permissions.
4. Return to Datalyr and choose the primary ad account.
5. Select **Set as primary**.
The source should change to **Connected**. An account that is authorized but has no primary account selected will remain incomplete.
To switch the primary account, disconnect Meta and reconnect it. Disconnecting clears the existing synced Meta data before a different account is selected.
## Set up conversion delivery
Connecting Meta does not decide which Datalyr events should be sent. Open **Conversions** and create a rule for the event you care about, such as a purchase, lead, or trial start. Choose Meta as the destination, select the destination event, and review whether the value should come from the event or remain fixed.
Start with one high-value event. Confirm it works before adding several rules.
## Verify the connection
Check all three stages:
1. **Source:** Meta shows as connected in **Sources**, with the expected account.
2. **Reporting:** campaign data appears after the first sync. Use a recent date range with known spend.
3. **Delivery:** a matching Datalyr event creates a delivery attempt in **Conversions**.
Meta may process reporting and conversion data on a delay. A successful Datalyr delivery means Meta accepted the request; it does not guarantee that Meta will attribute or display it immediately.
## If your account is missing
* Confirm the authorizing Meta user has access to the ad account.
* Make sure you authorized the correct Meta profile and business.
* Ask a business administrator to grant the required access, then reconnect.
* If Datalyr says the connection needs configuration, finish the primary-account step.
Do not keep reconnecting a healthy source to fix a reporting difference. First compare the account, date range, timezone, and attribution settings.
# OpenAI Ads
Source: https://docs.datalyr.com/integrations/openai-ads
Connect an OpenAI Ads Conversions API key and pixel.
OpenAI Ads uses a direct credential connection. Datalyr asks for a Conversions API key and Pixel ID, then validates them before saving the source.
## Before you connect
In OpenAI Ads Manager, open **Settings → Conversions API** and copy:
* the API key
* the Pixel ID, which normally starts with `px_`
Treat the API key as a secret. Do not paste it into a public issue, browser script, or support screenshot.
## Connect OpenAI Ads
1. Open **Sources**.
2. Find **OpenAI Ads** and select **Connect**.
3. Paste the API key and Pixel ID.
4. Select **Connect**.
Datalyr runs a validation-only request immediately. Invalid credentials fail during setup instead of waiting for the first live conversion.
## Create a conversion rule
Open **Conversions**, create a rule for a Datalyr event, and choose OpenAI Ads as the destination. Select a supported destination event and decide whether its value is dynamic or fixed.
OpenAI Ads does not support every event name used by every other ad platform. Use the options presented in Datalyr instead of assuming a Meta or TikTok event has an identical OpenAI equivalent.
## Verify the connection
1. Confirm the source shows **Connected**.
2. Send one event that matches the enabled rule.
3. Check the rule's delivery result.
4. Confirm the destination received the event after its normal processing delay.
## Common errors
**API key rejected:** generate or copy the Conversions API key again. Make sure no spaces were added.
**Pixel ID not found:** copy the ID from **OpenAI Ads Manager → Settings → Conversions API** and confirm it belongs to the same account as the key.
**Credentials validate, but no conversion is delivered:** check the Datalyr event and rule. Credential validation only proves that the destination can be reached.
**The key may be exposed:** replace it in OpenAI Ads Manager, then update the Datalyr source. Any service using the old key must be updated separately.
The availability of OpenAI Ads and its account features depends on your OpenAI Ads account. Datalyr only shows and uses the fields supported by its current connection flow.
# Snapchat Ads
Source: https://docs.datalyr.com/integrations/snapchat-ads
Authorize Snapchat and send selected conversions to a Snap Pixel or app.
The Snapchat connection authorizes conversion delivery. Unlike Meta, Google, and TikTok, Snapchat does not ask you to choose an ad account in **Sources**. The destination asset is configured on each conversion rule.
## Before you connect
Use a Snapchat login with access to the organization and assets used by your campaigns. Keep the Snap Pixel ID for web or server events. For app conversions, keep the Snap App ID available if the rule asks for it.
## Connect Snapchat
1. Open **Sources**.
2. Find **Snapchat Ads** and select **Connect**.
3. Complete Snapchat authorization and approve the requested conversion access.
4. Return to Datalyr and confirm the source shows **Connected**.
There is no primary-account picker after authorization. This is expected.
## Configure a destination
1. Open **Conversions**.
2. Create a rule that matches a tracked Datalyr event.
3. Choose Snapchat as the destination.
4. Enter the Snap Pixel ID requested by the rule.
5. For an app-sourced event, add the Snap App ID when that option is available.
6. Save and enable the rule.
Copy IDs from Snapchat instead of typing them. A valid authorization paired with the wrong Pixel ID still sends data to the wrong place.
## Verify delivery
Trigger one controlled event and check it in this order:
1. The event exists in Datalyr.
2. The rule matched the event.
3. The delivery result was accepted by Snapchat.
4. The event appears in Snapchat's destination diagnostics after processing.
If the source is connected but there is no delivery attempt, the issue is the event or rule—not Snapchat authorization.
## Common problems
**Authorization fails:** verify the Snapchat user still has the needed organization access, allow pop-ups, and try the connection once more.
**Connected, but nothing is sent:** create or enable a Snapchat conversion rule and check its event filters.
**Destination rejects the event:** verify the Pixel ID or App ID, event type, timestamp, and required customer data shown in the delivery error.
**Wrong asset was used:** update the conversion rule. You do not need to reconnect Snapchat just to change a destination asset.
# TikTok Ads
Source: https://docs.datalyr.com/integrations/tiktok-ads
Connect a TikTok advertiser for reporting and conversion delivery.
Connect TikTok Ads to combine campaign performance with Datalyr revenue and send selected events through TikTok's server-side conversion flow.
## Before you connect
Use a TikTok account that can access the advertiser you want. If an agency or Business Center owns the advertiser, verify that the authorizing user has access before opening Datalyr.
Know the advertiser ID and currency. Datalyr shows both during account selection, which helps when account names repeat.
## Connect TikTok
1. Open **Sources**.
2. Find **TikTok Ads** and select **Connect**.
3. Complete TikTok authorization.
4. Choose the primary advertiser account.
5. Select **Set as primary**.
Datalyr uses that advertiser for campaign syncs and pins it to TikTok conversion rules created for the workspace.
## Create a conversion rule
Open **Conversions**, create a rule for a tracked event, and choose TikTok as the destination. Select the destination event that matches the customer action. Use the event's value for purchases when the source sends a reliable amount and currency.
Test one rule before enabling a full funnel. A broad rule that matches every event can create noisy or misleading optimization data.
## Verify the connection
* TikTok Ads shows **Connected** in **Sources**.
* The primary advertiser name and ID are correct.
* a recent report contains known TikTok spend or campaign activity after syncing.
* a test event appears in Datalyr and matches the rule.
* the delivery attempt is accepted or returns an actionable error.
Use TikTok's own event diagnostics for the destination-side view. Datalyr's delivery log is the first place to check because it separates matching failures from platform rejection.
## Common problems
**No advertiser accounts appear:** the authorizing user does not have access, or the wrong TikTok identity was used.
**Connection needs configuration:** OAuth finished, but the primary advertiser was not selected.
**Spend is missing:** confirm the advertiser ID and choose a date range with finalized campaign activity.
**Conversions are missing:** first confirm the event exists in Datalyr, then confirm the rule matched, then inspect the TikTok response. Do not reconnect the source when the failure is in the rule.
Switching advertisers requires disconnecting and reconnecting. Do this deliberately because the existing synced TikTok data is cleared as part of the change.
# AI chat
Source: https://docs.datalyr.com/product/ai-chat
Ask questions about the data in the current workspace.
AI chat can query the current workspace's analytics, events, users, attribution, ad performance, revenue, and usage.
## Open chat
Select **New chat** near the bottom of the main sidebar. Ask one specific question and include a date range when it matters.
Good prompts include:
* `Which campaigns drove the most revenue in the last 30 days?`
* `Compare Meta and Google spend and ROAS this week.`
* `Show the journey for user_123.`
* `Which event names appeared today?`
* `How much event usage is left in this billing period?`
## How workspace access works
Chat is scoped to the active workspace. Its read tools use the workspace's agent key and cannot switch to another workspace because a prompt asks it to.
If chat cannot query data, open **Settings → API** and check that the workspace has an agent key. Agent keys begin with `dk_agent_`. External Claude and Codex connections use [hosted MCP with OAuth](/datalyr-mcp), so you do not need to copy this key into those clients.
## Get a useful answer
1. Name the metric or object you want.
2. Add the date range and comparison period.
3. Specify a platform, campaign, user, or event when relevant.
4. Ask for the underlying rows when an aggregate looks surprising.
5. Verify high-impact conclusions in the corresponding Dashboard, Events, Users, or Reports view.
AI answers can be wrong or incomplete. Treat chat as a faster way to explore the workspace, not as a replacement for validating financial or campaign decisions.
Chat is read-only. It cannot change settings, billing, sources, or conversion rules.
# Conversions
Source: https://docs.datalyr.com/product/conversions
Review matched conversion rules and ad-platform delivery.
Conversions shows events that matched a workspace conversion rule, together with their value, destination, and delivery details.
## Understand the flow
```text theme={null}
Event received → rule matched → conversion created → destination delivery attempted
```
These are separate stages. An event can exist in **Events** without matching a rule. A conversion can exist here even when the destination rejects delivery.
## Review a conversion
1. Open **Conversions** and choose the date range.
2. Search by event, distinct ID, city, or rule name.
3. Filter by the available source, destination, or status fields.
4. Expand a row to see the summary, or open it for the complete details.
5. Compare the event value and currency with the original revenue source.
The toolbar totals conversion value in USD when a usable USD value is available. Mixed or missing currencies should be checked at the individual conversion level.
## Manage rules
Select **Manage rules** to create, edit, enable, disable, or remove rules. A rule defines:
* the source and event that can trigger it;
* the destination platform and connected account asset;
* the platform event name;
* how value and currency are determined;
* optional mappings required by the destination.
Create one clear rule for each intended source-to-destination flow. Before enabling production delivery, send a controlled test and inspect both the conversion record and the destination's diagnostics.
Two enabled rules can deliver the same business event twice. Duplicate only when each rule has a deliberate, independently verified destination.
## A conversion is missing
Find the source event in **Events** first. If it exists, check that the rule is enabled, listens to the exact event name and source, and targets an account that is still connected. If the conversion exists but was not delivered, open its detail view and fix the destination credentials, asset, mapping, or required customer data shown there.
# Dashboard
Source: https://docs.datalyr.com/product/dashboard
See the metrics and breakdowns that matter to your workspace.
The Dashboard is the fastest way to answer **what changed?** It combines first-party traffic with metrics from your connected sources.
## Set up your view
1. Open **Dashboard**.
2. Choose a date range. Dates use your workspace timezone.
3. Open the metric picker and select the metrics you want in the top row.
4. Select a metric to draw it on the chart.
Your visible metrics and selected chart are saved for the current workspace in this browser. Metrics from an integration only appear while that source is connected. If you reconnect it later, saved metrics return.
New workspaces start with **Visitors** and **Pageviews**. Connected sources add their available revenue, spend, and conversion metrics.
## Read the page
The number on each metric is the total for the selected range. The chart shows the selected metric over time, with its interval adjusted to the length of the range.
Below the chart, breakdown cards show useful context such as traffic, locations, devices, and tags. Treat a breakdown as a direction to investigate—not proof of a campaign result.
## A useful daily check
1. Compare visitors and pageviews with your normal baseline.
2. Check revenue and spend from connected sources.
3. Select the metric that changed most.
4. Use **Events**, **Users**, or **Reports** to inspect the underlying activity.
Dashboard and ad-platform numbers can differ because they use different timezones, attribution rules, and reporting delays. Compare the same dates and metric definition before treating a difference as an error.
## If a metric is missing
* Confirm the source is connected under **Sources**.
* Check that the selected range contains data from that source.
* Open the metric picker; a metric may simply be hidden.
* Refresh after connecting a new source.
# Events
Source: https://docs.datalyr.com/product/events
Inspect the raw activity Datalyr received.
Events is the best place to verify tracking and investigate a specific action. Each row is an event received by Datalyr—not an attributed conversion or a successful ad-platform delivery.
## Find an event
1. Open **Events** and choose a date range.
2. Search by event name, distinct ID, page, or city.
3. Use filters to narrow the event source and other available fields.
4. Select a bar in the volume chart to zoom into that time window. Clear the zoom chip to return to the full range.
5. Expand a row for a quick view, or open it for the complete event record.
The table is ordered by received time by default. Scroll to load more events. The total above the table comes from the complete range, so it can be larger than the rows currently loaded.
## What to inspect
* **Event name** — the stable action name, such as `pageview`, `signup`, or `purchase`.
* **Distinct ID** — the anonymous or known identity attached to the event.
* **Page and referrer** — where the action happened and where the visit came from.
* **Campaign fields** — UTMs and supported click identifiers captured on the journey.
* **Properties** — values supplied with the event, such as plan, product, amount, or currency.
* **Event and received times** — useful when offline queues or server processing delay an event.
You can copy the complete event from its detail panel when debugging an implementation.
## Verify a new event
1. Use a private window or a dedicated test account.
2. Perform the action once.
3. Search for the exact event name and your test identity.
4. Open the row and check the expected properties.
5. If it should become a conversion, verify the matching rule separately in **Conversions**.
Do not send passwords, access tokens, payment details, health information, or other sensitive values in event names, URLs, or properties.
## No event appears
Check the date range, clear filters, and confirm you are viewing the correct workspace. Then use **Live** to see whether any activity arrives. Browser privacy controls, consent settings, blocked-page filters, and ad blockers can prevent browser events from being collected.
# Using Datalyr
Source: https://docs.datalyr.com/product/index
Know where to verify traffic, journeys, conversions, and performance.
Once data is arriving, use each page for a different level of investigation.
| Page | Use it for |
| --------------- | ---------------------------------------------------------------------- |
| **Dashboard** | Spot changes in traffic, revenue, spend, and connected-source metrics. |
| **Live** | Watch a new installation or test journey in the last 30 minutes. |
| **Events** | Inspect the exact activity and properties Datalyr received. |
| **Users** | Follow one anonymous visitor or known customer across their journey. |
| **Conversions** | Review rule matches and delivery to ad platforms. |
| **Reports** | Keep a reusable personal board of metric charts. |
| **Track** | Create and measure campaign tracking links. |
## Follow the evidence
When a number looks wrong, move from summary to detail:
```text theme={null}
Dashboard or Report → Conversion → User journey → Source event
```
For a new installation, go the other direction:
```text theme={null}
Live → Event → User journey → Conversion → Dashboard
```
This keeps collection, identity, attribution, and delivery from being mistaken for the same thing.
Always confirm the workspace, date range, timezone, currency, and metric definition before comparing Datalyr with another platform.
# Live
Source: https://docs.datalyr.com/product/live
Watch recent visitors, events, and revenue while you test.
Live shows what is happening in the last 30 minutes. Use it while installing Datalyr, testing a funnel, or confirming that a campaign visit arrived with the right context.
## Run a clean test
1. Open **Live** before starting.
2. Open your site in a private window or use a test device.
3. Visit the landing page and complete the action you want to test.
4. Return to Live and select your visitor.
5. Check the visitor's page, referrer, device, location, event count, and recent activity.
The summary row shows **Active visitors**, **Revenue**, and **Top referrer** for the current 30-minute window. Visitors with matching activity can be grouped; select a visitor or group to inspect it.
## Refresh behavior
Live refreshes while you watch it. Use the refresh control when you need an immediate update. Recent data can still take a short moment to arrive, especially when a mobile SDK is offline or a server event is queued.
## Live versus Events
Use Live for immediate feedback. Use **Events** when you need a date range, search, filters, complete properties, or a durable investigation.
Seeing a purchase in Live confirms collection. It does not confirm that a conversion rule matched it, that attribution was recovered, or that an ad platform accepted it.
## Your visit is missing
* Confirm the Datalyr install is active on the page or app build you tested.
* Make sure you are in the correct workspace.
* Disable ad blockers for the test or use a first-party tracking domain.
* Check consent, Global Privacy Control, Do Not Track, and strict privacy settings.
* On mobile, bring the app online and allow the SDK time to flush queued events.
# Reports
Source: https://docs.datalyr.com/product/reports
Build a reusable board of metrics from Datalyr and connected sources.
Reports gives each important metric its own chart card. Use it for recurring checks that need more space than the Dashboard.
## Create a report card
1. Open **Reports** and select **New report**.
2. Choose one metric from the available catalog.
3. Choose the chart style and give the card a clear name.
4. Save it.
Only metrics supported by Datalyr or an active connected source are available. New workspaces begin with Visitors and Pageviews.
## Organize the board
* Drag cards to reorder them.
* Rename a card to state the question it answers.
* Duplicate a card before creating a close variation.
* Delete cards your team no longer uses.
* Turn on **vs prev period** to overlay the immediately preceding period.
The card layout is saved per workspace in the current browser. It is a personal working view, not a shared dashboard definition.
## Choose a useful range
Short ranges expose launches and outages. Longer ranges show trend. Dates use the workspace timezone. When previous-period comparison is enabled, a seven-day range is compared with the seven days immediately before it.
## Build a focused board
A practical acquisition board might include spend, visitors, conversions, revenue, and return on ad spend. A product board might use visitors, pageviews, signups, purchases, and revenue.
Keep each card to one metric. Use the same date range across the board, then open **Events**, **Users**, or the source platform to explain an unexpected change.
A card can disappear if its integration is disconnected or its metric is no longer available. Reconnect the source, then add the metric again if needed.
# Tracking links
Source: https://docs.datalyr.com/product/tracking-links
Create campaign links with UTMs and a stable Datalyr identifier.
Tracking links bundle a destination with campaign parameters and a unique `lyr` value. Use them for ads, partners, creators, QR codes, or any placement where you control the destination URL.
## Create a link
1. Open **Track** and select **Create link**.
2. Choose a verified first-party domain, or select **No domain (param link)**.
3. Enter the destination and a recognizable internal name.
4. Choose **Web page** or **App install**.
5. Add the source, medium, campaign, and any optional content or term values.
6. Create the link, copy it, and test it before publishing.
For app-install links, provide the appropriate App Store and Play Store destinations. Platform presets can help populate common ad macros, but you should confirm the generated URL against the ad platform before launch.
## Read link activity
The Track table shows each link and its activity. Search by name, `lyr`, destination, or campaign. Open a link to inspect its share URL and recent events. The selected date range controls activity stats, while search and filters control which saved links appear.
## UTMs and `lyr`
UTMs keep campaign labels readable across analytics and ad tools. The `lyr` value gives Datalyr a stable identifier for the link. Use both when possible; do not manually reuse one link's `lyr` on a different campaign.
A redirect click proves the link was opened. Attribution still depends on the rest of the journey reaching a tracked site or app and preserving supported identity or campaign context.
## Before launch
* Test the final ad URL, including platform macros.
* Confirm the redirect reaches the expected page or store.
* Open **Live** or **Events** and verify the visit contains the expected campaign values.
* Complete one test conversion and confirm it is connected to the link.
# Users
Source: https://docs.datalyr.com/product/users
Follow a visitor or known customer across their journey.
Users groups activity around the identity Datalyr received. It helps you move from aggregate metrics to one real customer journey.
## Find someone
1. Open **Users** and select a date range.
2. Search by ID, email, name, or location.
3. Use the filters to narrow the list.
4. Expand a user for a summary, or open the full detail view for their journey.
The page initially loads the most recent users. Busy workspaces can load more results, and very large date ranges may time out. If that happens, switch to the last hour or six hours, then search again.
## Read a journey
Start at the earliest visible touchpoint and follow the sequence forward:
1. Check the first page, referrer, and campaign information.
2. Look for the point where the anonymous visitor became known.
3. Confirm important product events appear in order.
4. Check revenue and conversion activity against the same identity.
An anonymous browser ID and your application's user ID are different identifiers. An `identify` call joins future and eligible known activity to the customer. It cannot safely infer that two unrelated anonymous visitors are the same person.
## Debug identity
Use a stable internal user ID when possible. Call `identify` after a trusted identity moment such as login or signup, and reset the SDK on logout or account switching.
If one customer appears as multiple users:
* confirm every runtime uses the same stable user ID;
* check that `identify` runs before or near the conversion;
* ensure logout resets identity on shared devices;
* do not generate a new user ID on every session.
Never alias IDs merely because they share a name, device, IP address, or other weak signal. Only join IDs you know belong to the same person.
# CheckoutChamp
Source: https://docs.datalyr.com/revenue/checkoutchamp
Connect funnel purchases, rebills, refunds, chargebacks, and cancellations.
CheckoutChamp uses a global head script for browser identity and separate Export Profile URLs for transaction lifecycle events.
## Set up the browser
Open the CheckoutChamp source in **Sources** and copy the Global Head Script into **Account Settings → Global Scripts** in CheckoutChamp. Publish the funnel and confirm a `pageview` appears in Datalyr.
## Add Export Profiles
Datalyr provides a separate URL for:
* Purchase
* Refund
* Chargeback
* Recurring subscription rebill
* Subscription cancellation
Create one CheckoutChamp Export Profile for each lifecycle event you use and paste the matching URL exactly. The URL includes CheckoutChamp field placeholders; do not replace them with example values.
## Verify
1. Test the landing and checkout pages in a private browser window.
2. Complete a controlled order.
3. Confirm the purchase has an order ID, amount, currency, and customer identity.
4. Trigger a supported refund or cancellation test and confirm it arrives separately.
A single purchase URL is not enough for refunds, rebills, chargebacks, or cancellations. Configure every lifecycle Export Profile you report on.
# Ecommerce revenue
Source: https://docs.datalyr.com/revenue/ecommerce
Track orders, customers, refunds, and the storefront journey.
Ecommerce attribution needs both sides of the order: storefront tracking captures why the customer arrived, and the commerce source supplies the final payment record.
## Before you connect
Install web tracking on every landing and storefront page. For Shopify, use the [Shopify install](/installation/shopify) so the App Embed and Web Pixel cover storefront and checkout surfaces.
## Setup
Open **Sources** and connect Shopify or Checkout Champ. Complete every step shown by the source dialog.
The source should show as connected without an error or action-needed state.
Start in a private window with test UTM parameters, view a product, and continue through checkout.
Use the platform's supported test payment method. Record the order ID, total, currency, and customer email.
Find it in **Events**, then open the customer in **Users** to confirm the visit and order are connected.
## Shopify metrics
Datalyr can report gross revenue, net revenue, refunded amount, paid orders, average order value, unique customers, first-time and repeat orders, items sold, discounted orders, and completed checkouts. Net revenue is gross revenue minus recorded refunds.
## Keep amounts comparable
Compare the same date range, timezone, currency, and order state. A platform may show authorized, pending, test, or unpaid orders in a view that Datalyr does not count as paid revenue.
Taxes, shipping, discounts, and platform fees can also change which total you are comparing. Start with one known order and compare its transaction-level amount before comparing an entire month.
## Common failures
* **Order is missing:** confirm it reached the paid state and the source is connected to the correct account.
* **Order exists but has no campaign:** the landing visit was not tracked, the Shopify App Embed was off, or identity was lost before checkout.
* **Revenue is doubled:** the same order is arriving from more than one source or custom purchase event.
* **Totals differ:** align order status, timezone, currency, refunds, and the definition of gross versus net revenue.
Fix missing attribution before scaling paid traffic. A later backfill can restore orders, but it cannot recreate browser context that was never captured.
# Revenue
Source: https://docs.datalyr.com/revenue/index
Connect payments to the visits, users, and campaigns that created them.
Connect the system that owns the final payment record. Datalyr combines that revenue with customer activity; it should not replace your billing platform as the ledger.
## Choose the source
| Business model | Recommended source | Typical data |
| ------------------------ | ----------------------- | ------------------------------------------------------------ |
| Shopify store | Shopify | Orders, customers, checkouts, cancellations, refunds |
| SaaS or web subscription | Stripe | Payments, subscriptions, invoices, refunds, disputes |
| Mobile subscription | RevenueCat or Superwall | Trials, purchases, renewals, cancellations, billing failures |
| Whop business | Whop | Purchases, subscriptions, cancellations |
| Checkout funnel | Checkout Champ | Purchases, rebills, refunds, chargebacks, cancellations |
## Connect revenue
Confirm a visit or app event appears before connecting revenue. Attribution needs the activity that happened before payment.
Find the platform that owns the transaction and select **Connect**.
Authorize the account or enter the credentials and webhook values requested in the connection dialog.
Use a sandbox or test mode where supported. Keep the transaction ID for comparison.
Open **Events**, find the transaction, and check its amount, currency, customer, source, and transaction ID.
## Use one owner per transaction
Do not send the same purchase from an integration, a webhook, and custom SDK code. Duplicate reporting can inflate revenue even when the event names differ.
When two systems observe the same payment, choose the platform that creates the final charge. For example, use Stripe for a Stripe-hosted SaaS checkout and Shopify for a Shopify order.
## Source guides
Orders, refunds, customers, and storefront attribution.
Payments, subscriptions, invoices, and visitor metadata.
Creator purchases and subscriptions.
Funnel orders, upsells, rebills, refunds, and chargebacks.
Mobile subscriptions and purchases.
Paywall, trial, and subscription events.
## What to verify
A correct transaction includes a unique transaction or order ID, numeric amount, ISO currency, source, timestamp, and a customer identifier when available. The customer journey should contain the landing visit before the purchase.
Orders, customers, and store revenue.
Trials, renewals, and cancellations.
How returned money affects reporting.
Move from revenue to contribution profit.
# Profit tracking
Source: https://docs.datalyr.com/revenue/profit
Combine net revenue, ad spend, and costs into a useful profit view.
Profit is a derived view. Fix the inputs before trusting the result.
## Start with the definition
A practical contribution-profit view is:
```text theme={null}
Net revenue − ad spend − product costs − included fees = contribution profit
```
Decide which costs belong in your operating view before comparing Datalyr with an accounting system. Datalyr is designed for acquisition decisions, not general-ledger reconciliation.
## Setup order
Check several known transactions and refunds. Do not configure profit while revenue is still duplicated or missing.
Open **Sources** and connect the platforms spending money in the selected workspace.
Configure product costs, fees, or other available cost adjustments consistently. Avoid mixing tax-inclusive and tax-exclusive values.
Use the same date range, timezone, and currency across revenue, spend, and cost inputs.
Reconcile one day or a handful of known orders before reviewing a full month.
## Read the result
* **Gross revenue** is sales before recorded refunds.
* **Net revenue** subtracts recorded refunds.
* **Ad spend** comes from connected ad-platform accounts.
* **Product costs and fees** depend on the cost inputs enabled for the workspace.
* **Profit** is only comparable when all inputs cover the same period and currency basis.
## Why profit can look wrong
* One ad account is missing or connected to the wrong workspace.
* Refunds arrived after the selected period.
* Product costs are incomplete for some items.
* Revenue and spend use different timezones.
* Source currencies are being compared without the same conversion basis.
* Gross revenue is being compared with a net-revenue calculation.
Reconcile inputs independently: revenue first, then refunds, then spend, then costs. A single profit total cannot tell you which input is wrong.
# Refunds
Source: https://docs.datalyr.com/revenue/refunds
See how full and partial refunds change net revenue.
Refunds come from the connected revenue source. They can arrive days or months after the original payment.
## What changes
For Shopify and Stripe, **Net revenue** is gross revenue minus the recorded refunded amount. A partial refund reduces net revenue by the partial amount; it does not remove the original order.
A cancellation is not automatically a refund. Canceling a subscription stops future billing, while a refund returns money from a completed payment.
## Verify a refund
Confirm the refund is final in Shopify, Stripe, or the billing provider—not merely requested or pending.
Record the original transaction ID, refund ID, amount, currency, and completion time.
Locate the refund and confirm it refers to the expected customer and original transaction.
Use the same timezone, currency, and date range. Compare gross revenue, refunded amount, and net revenue separately.
## Reporting dates
Refund activity occurs when the source reports it. Depending on the report and date grouping, the refund may be visible in the period it was processed rather than the period of the original sale. Always inspect the individual transaction before assuming a totals problem.
## Common failures
* **Refund is missing:** it is still pending, the wrong source account is connected, or the source connection needs attention.
* **Refund amount differs:** compare partial versus full refund amounts and currency conversion.
* **Revenue still looks high:** the selected metric is gross revenue rather than net revenue.
* **A cancellation did not reduce revenue:** no completed payment was refunded.
Do not send a refund as a new negative purchase. Let the authoritative revenue source report it so the original transaction relationship stays intact.
# RevenueCat
Source: https://docs.datalyr.com/revenue/revenuecat
Receive mobile subscription and purchase events from RevenueCat.
RevenueCat sends subscription, trial, and one-time purchase activity through a workspace-specific webhook.
## Connect RevenueCat
1. Open **Sources → RevenueCat**.
2. Enter the RevenueCat App ID.
3. Choose `production` or `sandbox`; production is the default.
4. Copy the Datalyr webhook URL into **RevenueCat → Project Settings → Integrations**.
5. Add the webhook secret when signature verification is configured.
## Identity
Use the same stable App User ID in RevenueCat and your Datalyr mobile SDK identification when possible. Anonymous or changed IDs can cause a purchase to appear without the expected customer journey.
## Verify
Send a RevenueCat test event or complete a sandbox purchase. Confirm the environment, product, value, currency, and App User ID before testing a production purchase.
# Shopify
Source: https://docs.datalyr.com/revenue/shopify
Understand Shopify orders, refunds, customers, and revenue in Datalyr.
The Shopify source sends commerce activity to Datalyr. Storefront tracking supplies the visit and campaign context used to attribute that activity.
## Before you start
Complete both parts of the Shopify installation:
* Connect the permanent `myshopify.com` domain in **Sources**
* Install the Web Pixel and enable the Datalyr App Embed
See [Install on Shopify](/installation/shopify) for the full installation flow.
## What Shopify sends
Datalyr records activity for:
* Paid, fulfilled, cancelled, and refunded orders
* Completed and abandoned checkouts
* New customers
* Order value, discounts, taxes, shipping, and currency when supplied
* Product and line-item details available in the Shopify event
Reports expose Shopify metrics including gross revenue, net revenue, refunded value, paid orders, average order value, customers, first-time and repeat orders, discount usage, and completed checkouts.
## How attribution works
The browser visit and Shopify order must share enough identity to form one journey. The App Embed captures the landing page, UTMs, click IDs, and visitor ID. The Shopify install carries supported identity into checkout and the order webhook supplies customer and transaction data.
A connected store can send orders while storefront tracking is incomplete. Revenue will appear, but those orders may not have the original campaign or click ID.
## Verify a paid order
1. Open the storefront in a private browser window with test UTMs.
2. Confirm the landing `pageview` in **Events**.
3. Complete Shopify's supported test-payment flow.
4. Find the paid order event and confirm its order ID, value, and currency.
5. Open the customer in **Users** and confirm the storefront visit and order share a journey.
6. Refund the test order and confirm the refund arrives before validating net revenue.
## Avoid duplicates
Do not keep a manually pasted Datalyr web snippet when the App Embed owns storefront tracking. Do not also send the same Shopify order through custom server code unless both paths use a verified shared deduplication ID.
## Common issues
* **Orders but no attribution:** enable and save the App Embed, then test with a new order.
* **Storefront but no checkout events:** install the Web Pixel from the Shopify source.
* **Store domain rejected:** use the permanent `myshopify.com` domain without a protocol or path.
* **Refund totals differ:** compare the same timezone, currency, and refund processing period.
# Stripe
Source: https://docs.datalyr.com/revenue/stripe
Connect Stripe payments and deterministically link them to web visitors.
Stripe sends payments, subscriptions, invoices, refunds, and disputes to Datalyr. Add the Datalyr visitor ID to Stripe objects so the payment can be linked to the exact web journey.
## Connect Stripe
Find **Stripe** and select **Connect**.
Complete Stripe Apps OAuth and choose the Stripe account used by this workspace.
Follow the setup dialog that opens after authorization. Choose the snippet matching your Stripe integration.
Use the supported Stripe test or live flow and verify the resulting event in Datalyr.
No manual Stripe webhook endpoint is required for the current OAuth connection.
## Checkout Sessions
Get the current Datalyr identity in the browser:
```ts theme={null}
const datalyrStripe = datalyr.getStripeMetadata()
// { client_reference_id, metadata: { visitor_id } }
```
Pass it when your server creates the Checkout Session:
```ts theme={null}
const session = await stripe.checkout.sessions.create({
...datalyrStripe,
mode: 'subscription',
line_items: [{ price: 'price_123', quantity: 1 }],
success_url: 'https://example.com/success',
cancel_url: 'https://example.com/pricing'
})
```
The completed Checkout Session uses `client_reference_id` for deterministic attribution.
## PaymentIntents
```ts theme={null}
const visitorId = datalyr.getVisitorId()
await stripe.paymentIntents.create({
amount: 9900,
currency: 'usd',
metadata: { visitor_id: visitorId }
})
```
## Subscriptions
Add `metadata.visitor_id` to the Subscription. Subscription metadata propagates into the supported invoice flow so later renewals remain associated with the original customer identity.
```ts theme={null}
await stripe.subscriptions.create({
customer: 'cus_123',
items: [{ price: 'price_123' }],
metadata: { visitor_id: visitorId }
})
```
## Stripe Payment Links
The current Web SDK automatically decorates supported `buy.stripe.com` Payment Links and Stripe pricing-table or buy-button embeds. It adds the visitor reference without requiring custom checkout code. Do not append unsupported parameters to already-created `checkout.stripe.com` Session URLs.
## What appears in Datalyr
Stripe reporting includes revenue, purchases, conversions, net revenue, refunds, disputes, and subscription lifecycle metrics such as new and cancelled subscriptions when present in the source data.
## Verify attribution
1. Open the website in a private window with test UTMs.
2. Confirm the `pageview` event and visitor ID.
3. Complete a Stripe test payment through the same integration path used in production.
4. Find the Stripe event and confirm value, currency, customer, and transaction identifiers.
5. Open the customer journey and confirm the web visit precedes the payment.
Email matching is a fallback, not the preferred implementation. Use `client_reference_id` or `metadata.visitor_id` whenever you control Stripe object creation.
# Subscription revenue
Source: https://docs.datalyr.com/revenue/subscriptions
Track trials, first payments, renewals, cancellations, and mobile subscriptions.
Use the billing system that owns the subscription record: Stripe for most web subscriptions, or RevenueCat and Superwall for mobile purchases.
## Connect the lifecycle
Install the Web or mobile SDK and identify the customer with a stable application user ID.
Open **Sources**, select Stripe, RevenueCat, Superwall, or Whop, and complete the requested authorization or credential setup.
Use the same application user ID in Datalyr and the billing provider where supported. For mobile, use the RevenueCat or Superwall helper in the SDK reference.
Start a trial or paid subscription in the provider's test environment and confirm the event appears.
Trigger a cancellation, renewal, or billing-failure test when the provider supports it.
## Understand the events
A subscription is not one conversion repeated forever. It has a lifecycle:
* **Trial start:** access begins without a completed paid conversion.
* **Trial conversion or initial purchase:** the first successful paid period.
* **Renewal:** another successful billing period for the existing subscription.
* **Cancellation:** future renewal is stopped; access may remain until period end.
* **Expiration:** access ends.
* **Billing failure:** a charge failed and may be retried.
* **Refund:** money from a completed payment is returned.
RevenueCat and Superwall reporting includes gross and net revenue, new subscriptions, renewals, cancellations, trials, billing failures, one-time purchases, platform revenue, and customer counts. Stripe reporting includes revenue, purchases, net revenue, refunds, disputes, new subscriptions, canceled subscriptions, and subscription payments.
## Avoid common counting mistakes
Do not count trial starts as paid customers. Do not treat renewals as new-customer conversions. For acquisition reporting, separate initial paid conversions from recurring revenue; use both when evaluating lifetime value.
## If revenue is not joined to a user
Compare the stable ID sent by your app with the identifier stored by the billing provider. Anonymous billing IDs, changed user IDs, and identifying only after purchase are the most common breaks. Test with a brand-new customer after correcting identity.
A complete test journey shows the acquisition visit, sign-in identity, trial or purchase, and later lifecycle events on the same customer.
# Superwall
Source: https://docs.datalyr.com/revenue/superwall
Receive paywall, trial, subscription, and purchase activity from Superwall.
Superwall sends mobile monetization events through a workspace-specific webhook.
## Connect Superwall
1. Open **Sources → Superwall**.
2. Enter the application Bundle ID.
3. Add the optional Superwall Project ID when your setup uses it.
4. Copy the Datalyr webhook URL into Superwall.
5. Add the webhook secret for signature verification.
## Pass Datalyr identity
Use the mobile SDK helper to retrieve attributes for Superwall:
```ts theme={null}
const attributes = Datalyr.getSuperwallAttributes()
```
The iOS SDK exposes the equivalent `getSuperwallAttributes()` helper. Set these attributes in Superwall before presenting the paywall when you need the purchase linked to the current Datalyr identity.
## Verify
Test a paywall outcome in the correct app environment. Confirm the Bundle ID, customer identity, product, value, and currency in **Events**.
# Whop
Source: https://docs.datalyr.com/revenue/whop
Receive Whop purchases and subscriptions in Datalyr.
The Whop source uses a workspace-specific webhook to send purchases and subscriptions to Datalyr.
## Connect Whop
1. Open **Sources**, choose **Whop**, and select **Connect**.
2. Copy the webhook URL displayed by Datalyr.
3. In Whop, open **Developer → Webhooks** and create the endpoint.
4. Paste the Whop webhook secret into Datalyr when you want signature verification.
5. Save the connection and send a test event from Whop.
The webhook secret is optional in the connection UI, but signature verification is strongly recommended for production.
## Link a checkout to the visitor
The Web SDK exposes Whop checkout metadata:
```ts theme={null}
const metadata = datalyr.getWhopCheckoutMetadata()
// { visitor_id: '...' }
```
Attach this metadata when your Whop checkout flow supports it. It gives Datalyr a deterministic link to the earlier web visit.
## Verify
Confirm a test purchase or subscription appears in **Events**, then open the customer in **Users** and check that the earlier landing visit is present.
# SDK Reference
Source: https://docs.datalyr.com/sdk-reference/index
Add Datalyr to your website, server, or mobile app.
Choose the SDK that matches where your code runs.
| SDK | Current version |
| --------------------- | --------------- |
| Web | `1.7.6` |
| Node.js | `1.3.1` |
| iOS | `2.1.8` |
| React Native and Expo | `1.7.13` |
Track website activity, identity, and attribution in the browser.
Track trusted events from your backend.
Track app activity and attribution in a native iOS app.
Track mobile apps built with React Native or Expo.
Use one SDK for each runtime. For example, use the Web SDK in the browser and the Node.js SDK on your server.
# iOS SDK
Source: https://docs.datalyr.com/sdk-reference/ios
Track native iOS apps with DatalyrSDK.
The iOS SDK supports iOS 13 and later.
## Install with Swift Package Manager
In Xcode, select **File → Add Package Dependencies** and add:
```text theme={null}
https://github.com/datalyr/swift
```
Add the `DatalyrSDK` product to your app target.
## Initialize
```swift theme={null}
import DatalyrSDK
Task {
try await DatalyrSDK.configure(
apiKey: "dk_your_api_key"
)
}
```
## Track an event
```swift theme={null}
await datalyrTrack("signup_completed", properties: [
"plan": "pro"
])
```
## Identify a user
```swift theme={null}
await datalyrIdentify("user_123", properties: [
"email": "person@example.com"
])
```
## Track a screen
```swift theme={null}
PricingView()
.datalyrScreen("Pricing")
```
```swift theme={null}
await datalyrScreen("Pricing")
```
## Core methods
| Method | Use it to |
| ------------------------------- | --------------------------------- |
| `DatalyrSDK.configure(...)` | Initialize the shared SDK. |
| `datalyrTrack(...)` | Track an event. |
| `datalyrScreen(...)` | Track a screen view. |
| `datalyrIdentify(...)` | Identify a user. |
| `datalyrAlias(...)` | Link two IDs for the same user. |
| `datalyrReset()` | Clear identity on logout. |
| `datalyrFlush()` | Send queued events immediately. |
| `datalyrGetAnonymousId()` | Read the persistent anonymous ID. |
| `datalyrTrackPurchase(...)` | Track purchase revenue. |
| `datalyrTrackSubscription(...)` | Track subscription revenue. |
Call `datalyrReset()` when a user signs out.
## CocoaPods
```ruby theme={null}
pod 'DatalyrSDK', '~> 2.1.8'
```
Then run `pod install` and open the generated workspace.
## Configuration
```swift theme={null}
let config = DatalyrConfig(
apiKey: "dk_your_api_key",
debug: false,
maxRetries: 3,
timeout: 15,
batchSize: 10,
flushInterval: 10,
maxQueueSize: 1000,
enableAutoEvents: true,
enableAttribution: true
)
try await DatalyrSDK.shared.initialize(config: config)
```
| Option | Default | What it controls |
| ------------------- | -------- | ------------------------------------------- |
| `apiKey` | Required | Workspace API key. |
| `debug` | `false` | Development logging. |
| `maxRetries` | `3` | Delivery retries. |
| `retryDelay` | `1` | Delay between retries in seconds. |
| `timeout` | `15` | Request timeout in seconds. |
| `batchSize` | `10` | Events sent in each batch. |
| `flushInterval` | `10` | Automatic flush interval in seconds. |
| `maxQueueSize` | `1000` | Maximum queued events. |
| `enableAutoEvents` | `true` | App lifecycle and session events. |
| `enableAttribution` | `true` | Deep-link and campaign attribution. |
| `autoEventConfig` | — | Fine-grained automatic event settings. |
| `skadTemplate` | — | SKAdNetwork template for conversion values. |
## Automatic events
```swift theme={null}
let autoEvents = AutoEventConfig(
trackSessions: true,
trackScreenViews: true,
trackAppUpdates: true,
trackPerformance: false,
autoTrackScreenViews: false
)
```
Automatic UIKit screen tracking is opt-in. For SwiftUI, use the `.datalyrScreen()` modifier.
## Identity
```swift theme={null}
await datalyrIdentify("user_123", properties: [
"email": "person@example.com",
"plan": "pro"
])
let anonymousId = datalyrGetAnonymousId()
```
Use `datalyrAlias` only to join two IDs for the same person. Call `datalyrReset()` on logout or account switching.
## Revenue and subscriptions
```swift theme={null}
await datalyrTrackPurchase(
value: 99.99,
currency: "USD",
productId: "pro_yearly"
)
await datalyrTrackSubscription(
value: 19.99,
currency: "USD",
plan: "pro_monthly"
)
```
The SDK also includes helpers for add to cart, content views, checkout, registration, search, leads, and payment information.
## Attribution and deep links
Pass incoming links to the SDK:
```swift theme={null}
await DatalyrSDK.shared.handleDeepLink(url)
```
Read the current state when you need it:
```swift theme={null}
let attribution = DatalyrSDK.shared.getAttributionData()
let journey = DatalyrSDK.shared.getJourney()
let summary = DatalyrSDK.shared.getJourneySummary()
```
## App Tracking Transparency
```swift theme={null}
let status = await DatalyrSDK.shared.requestTrackingAuthorization()
let idfa = DatalyrSDK.shared.getIDFA()
```
ATT controls access to advertising identifiers. It is not a complete analytics-consent system. Your app remains responsible for consent handling and accurate App Store privacy disclosures.
## RevenueCat and Superwall
```swift theme={null}
let revenueCat = DatalyrSDK.shared.getRevenueCatAttributes()
let superwall = DatalyrSDK.shared.getSuperwallAttributes()
```
Pass these attributes to the matching SDK when you need Datalyr identity available in subscription events.
## Diagnostics
```swift theme={null}
let status = DatalyrSDK.shared.getStatus()
await datalyrFlush()
```
Use `getStatus()` during setup verification and `datalyrFlush()` before a controlled shutdown or background transition when immediate delivery matters.
# Node.js SDK
Source: https://docs.datalyr.com/sdk-reference/node
Track trusted backend events with @datalyr/api.
The Node.js SDK tracks events from servers, jobs, and webhooks. It requires Node.js 14.17 or later.
## Install
```bash theme={null}
npm install @datalyr/api
```
## Initialize
```ts theme={null}
import { Datalyr } from '@datalyr/api'
const datalyr = new Datalyr({
apiKey: process.env.DATALYR_API_KEY
})
```
## Track an event
```ts theme={null}
await datalyr.track({
event: 'purchase',
userId: 'user_123',
eventId: 'order_1001',
timestamp: new Date(),
properties: {
value: 99.99,
currency: 'USD'
}
})
```
Use a stable `eventId` for webhook events. If the source retries the webhook, Datalyr can recognize the duplicate.
## Identify a user
```ts theme={null}
await datalyr.identify('user_123', {
email: 'person@example.com',
plan: 'pro'
})
```
## Core methods
| Method | Use it to |
| ----------------------------------- | --------------------------------------------- |
| `track(options)` | Track a backend event. |
| `identify(userId, traits?)` | Attach traits to a user. |
| `alias(newUserId, previousId?)` | Link two IDs for the same user. |
| `page(userId, name?, properties?)` | Track a server-rendered page view. |
| `trackPurchase(userId, properties)` | Track revenue with a required finite `value`. |
| `flush()` | Send queued events immediately. |
| `close()` | Flush events and stop timers before shutdown. |
## Shut down cleanly
```ts theme={null}
await datalyr.close()
```
Call `close()` in short-lived scripts, workers, and graceful shutdown handlers so queued events have time to send.
## Configuration
```ts theme={null}
const datalyr = new Datalyr({
apiKey: process.env.DATALYR_API_KEY,
flushAt: 20,
flushInterval: 10_000,
timeout: 10_000,
retryLimit: 3,
maxQueueSize: 1_000,
closeTimeout: 30_000,
onError: (event, error) => console.error(error),
onDrop: (events, reason) => console.error(reason, events)
})
```
| Option | Default | What it controls |
| --------------- | -------- | ---------------------------------------------- |
| `apiKey` | Required | Workspace API key. |
| `flushAt` | `20` | Events queued before an automatic send. |
| `flushInterval` | `10000` | Automatic flush interval in milliseconds. |
| `timeout` | `10000` | Request timeout in milliseconds. |
| `retryLimit` | `3` | Retries during a send attempt. |
| `maxQueueSize` | `1000` | Maximum queued events. |
| `closeTimeout` | `30000` | Time allowed for `close()` to drain the queue. |
| `debug` | `false` | Development logging. |
| `onError` | — | Called for every delivery failure. |
| `onDrop` | — | Called when events are permanently dropped. |
## Event identity
Prefer the object form of `track`:
```ts theme={null}
await datalyr.track({
event: 'trial_started',
userId: 'user_123',
anonymousId: 'anon_from_browser',
properties: { plan: 'pro' }
})
```
Provide `userId`, `anonymousId`, or both. If you omit both, the SDK creates a new anonymous ID for that call, so separate calls will not form a continuous journey.
## Idempotency and timestamps
For webhooks, pass the source event ID and original timestamp:
```ts theme={null}
await datalyr.track({
event: 'invoice_paid',
userId: customer.id,
eventId: stripeEvent.id,
timestamp: stripeEvent.created,
properties: { value: 49, currency: 'USD' }
})
```
`timestamp` accepts an ISO 8601 string, a `Date`, epoch seconds, or epoch milliseconds.
## Identity methods
```ts theme={null}
await datalyr.identify('user_123', { email: 'person@example.com' })
await datalyr.alias('user_123', 'temporary_id')
await datalyr.page('user_123', 'Pricing', { variant: 'A' })
```
## Track revenue
```ts theme={null}
await datalyr.trackPurchase(
'user_123',
{ value: 99.99, currency: 'USD', product_id: 'pro_yearly' },
{ eventId: 'order_1001', timestamp: new Date() }
)
```
`value` must be a finite number. Currency values are normalized to uppercase.
## Serverless functions
Use `flush()` at the end of an invocation when the SDK instance may be reused:
```ts theme={null}
await datalyr.flush()
```
Use `close()` only when the process is shutting down. Once closed, the instance cannot accept more events.
# React Native SDK
Source: https://docs.datalyr.com/sdk-reference/react-native
Track React Native and Expo apps with @datalyr/react-native.
The React Native SDK supports React Native 0.72 or later and React 18 or later.
## Install
```bash theme={null}
npm install @datalyr/react-native
```
For an iOS project, install pods after adding the package:
```bash theme={null}
cd ios && pod install
```
## Initialize
```ts theme={null}
import { Datalyr } from '@datalyr/react-native'
await Datalyr.initialize({
apiKey: 'dk_your_api_key',
enableAutoEvents: true,
enableAttribution: true
})
```
For Expo, import the Expo entry instead:
```ts theme={null}
import { Datalyr } from '@datalyr/react-native/expo'
```
## Track an event
```ts theme={null}
await Datalyr.track('signup_completed', {
plan: 'pro'
})
```
## Identify a user
```ts theme={null}
await Datalyr.identify('user_123', {
email: 'person@example.com'
})
```
## Track a purchase
```ts theme={null}
await Datalyr.trackPurchase(99.99, 'USD', 'product_123')
```
## Core methods
| Method | Use it to |
| ------------------------------- | ------------------------------- |
| `initialize(config)` | Initialize the SDK. |
| `track(name, properties?)` | Track an event. |
| `screen(name, properties?)` | Track a screen view. |
| `identify(userId, properties?)` | Identify a user. |
| `alias(newUserId, previousId?)` | Link two IDs for the same user. |
| `reset()` | Clear identity on logout. |
| `flush()` | Send queued events immediately. |
| `trackPurchase(...)` | Track purchase revenue. |
The SDK can automatically track app lifecycle events and attribution. Call `reset()` whenever a user signs out or switches accounts.
## Configuration
```ts theme={null}
await Datalyr.initialize({
apiKey: 'dk_your_api_key',
debug: false,
maxRetries: 3,
retryDelay: 1000,
timeout: 15000,
batchSize: 10,
flushInterval: 30000,
maxQueueSize: 100,
enableAutoEvents: true,
enableAttribution: true,
enableWebToAppAttribution: true
})
```
| Option | Default | What it controls |
| --------------------------- | -------- | ------------------------------------------------------------ |
| `apiKey` | Required | Workspace API key. |
| `workspaceId` | — | Optional workspace identifier. |
| `debug` | `false` | Development logging. |
| `maxRetries` | `3` | Delivery retries. |
| `retryDelay` | `1000` | Delay between retries in milliseconds. |
| `timeout` | `15000` | Request timeout in milliseconds. |
| `batchSize` | `10` | Events sent in each batch. |
| `flushInterval` | `30000` | Automatic flush interval in milliseconds. |
| `maxQueueSize` | `100` | Maximum queued events. |
| `enableAutoEvents` | `true` | App lifecycle and session tracking. |
| `enableAttribution` | `true` | Campaign and deep-link attribution. |
| `enableWebToAppAttribution` | `true` | Web-to-app matching when supported. |
| `skadTemplate` | — | iOS conversion template: ecommerce, gaming, or subscription. |
Deprecated aliases such as `apiUrl`, `maxEventQueueSize`, `autoEvents`, and `retryConfig` are still accepted but should not be used in new implementations.
## Identity
```ts theme={null}
await Datalyr.identify('user_123', {
email: 'person@example.com',
plan: 'pro'
})
const anonymousId = Datalyr.getAnonymousId()
```
Use `alias` only when the old and new IDs belong to the same person. `reset()` rotates local identity and clears user-scoped attribution.
## Screens
Track a screen manually:
```ts theme={null}
await Datalyr.screen('Pricing', { source: 'tab_bar' })
```
For React Navigation, use `datalyrScreenTracking` or `createScreenTrackingListeners`. For Expo Router, use the Expo entry and `useDatalyrScreenTracking`.
## Revenue events
```ts theme={null}
await Datalyr.trackPurchase(99.99, 'USD', 'pro_yearly')
await Datalyr.trackSubscription(19.99, 'USD', 'pro_monthly')
```
The SDK also includes helpers for add to cart, content views, checkout, registration, search, leads, and payment information.
## Attribution and journeys
```ts theme={null}
const attribution = Datalyr.getAttributionData()
const journey = Datalyr.getJourney()
const summary = Datalyr.getJourneySummary()
```
Use `setAttributionData()` only when your app already has trusted campaign information that the SDK could not capture automatically.
## Deep links
The SDK captures supported deep-link and install-referrer values when attribution is enabled. You can read a deferred result with:
```ts theme={null}
const deferred = Datalyr.getDeferredAttributionData()
```
## iOS tracking authorization
```ts theme={null}
await Datalyr.updateTrackingAuthorization(true)
```
This controls advertiser tracking behavior on iOS. It does not replace a complete analytics-consent implementation.
## RevenueCat and Superwall
```ts theme={null}
const revenueCat = Datalyr.getRevenueCatAttributes()
const superwall = Datalyr.getSuperwallAttributes()
```
Pass these attributes to the matching subscription SDK when needed.
## Queue and lifecycle
Events created before initialization are temporarily buffered. Offline events are queued and retried when connectivity returns.
```ts theme={null}
await Datalyr.flush()
Datalyr.destroy()
```
Use `flush()` when immediate delivery matters. `destroy()` stops listeners and background work; only call it when tearing down the SDK.
# Web SDK
Source: https://docs.datalyr.com/sdk-reference/web
Track website activity, users, and attribution with @datalyr/web.
The Web SDK tracks website activity, user identity, sessions, and attribution.
## Install
```bash theme={null}
npm install @datalyr/web
```
```ts theme={null}
import datalyr from '@datalyr/web'
datalyr.init({ workspaceId: 'YOUR_WORKSPACE_ID' })
await datalyr.ready()
```
```html theme={null}
```
Choose one installation method. Do not install the package and script tag on the same page.
## Track an event
```ts theme={null}
datalyr.track('signup_clicked', {
location: 'pricing_page'
})
```
## Identify a user
```ts theme={null}
datalyr.identify('user_123', {
email: 'person@example.com',
plan: 'pro'
})
```
Call `identify` after the user signs in or when you otherwise know their stable ID.
## Track a page
```ts theme={null}
datalyr.page({
title: 'Pricing',
variant: 'A'
})
```
The SDK tracks the first page view and SPA navigation by default. Use `page` when you need to record one manually.
## Core methods
| Method | Use it to |
| ---------------------------- | ----------------------------------------------- |
| `init(config)` | Initialize the SDK with a workspace ID. |
| `ready()` | Wait for asynchronous initialization to finish. |
| `track(name, properties?)` | Track an event. |
| `identify(userId, traits?)` | Attach a stable ID and traits to the visitor. |
| `page(properties?)` | Track a page view manually. |
| `alias(userId, previousId?)` | Link two IDs that belong to the same person. |
| `reset()` | Clear identity when a user signs out. |
| `flush()` | Send queued events immediately. |
| `optOut()` / `optIn()` | Change tracking preference. |
| `setConsent(consent)` | Apply analytics and marketing consent. |
## Privacy
```ts theme={null}
datalyr.setConsent({
analytics: true,
marketing: false
})
```
Use `reset()` on logout so the next user does not inherit the previous user’s identity.
## Configuration
Only `workspaceId` is required. These are the options most implementations need.
| Option | Type | Default | What it controls |
| ----------------------------- | ------------------------------------------- | ------------ | -------------------------------------------------------- |
| `workspaceId` | `string` | Required | The workspace that receives events. |
| `debug` | `boolean` | `false` | Console logging during development. |
| `trackPageViews` | `boolean` | `true` | Tracks the first page view. |
| `trackSPA` | `boolean` | `true` | Tracks client-side navigation. |
| `trackSessions` | `boolean` | `true` | Adds session data to events. |
| `sessionTimeout` | `number` | `60` | Session timeout in minutes. |
| `attributionWindow` | `number` | `90` | Attribution window in days. |
| `trackedParams` | `string[]` | `[]` | Additional URL parameters to capture. |
| `privacyMode` | `'standard' \| 'strict'` | `'standard'` | Limits collection in strict mode. |
| `respectGlobalPrivacyControl` | `boolean` | `true` | Respects the browser GPC signal. |
| `respectDoNotTrack` | `boolean` | `false` | Respects the browser DNT signal when enabled. |
| `cookieDomain` | `string \| 'auto'` | `'auto'` | Cookie domain used for identity. |
| `cookieExpires` | `number` | `365` | Cookie lifetime in days. |
| `autoIdentify` | `boolean` | `false` | Enables automatic email identification. |
| `enableContainer` | `boolean` | `true` | Loads configured container scripts. |
| `platform` | `'shopify' \| 'checkoutchamp' \| 'generic'` | — | Enables platform-specific behavior. |
| `stripePaymentLinks` | `boolean` | `true` | Adds Datalyr identity to supported Stripe payment links. |
Start with the defaults. Change batching, retry, cookie, or attribution options only when your implementation requires it.
## Identity
Use a stable ID from your own system:
```ts theme={null}
datalyr.identify(currentUser.id, {
email: currentUser.email,
plan: currentUser.plan
})
```
Useful identity methods:
| Method | Returns |
| ------------------ | ---------------------------------------------------- |
| `getAnonymousId()` | Persistent anonymous browser ID. |
| `getVisitorId()` | Current visitor ID. |
| `getUserId()` | Identified user ID, or `null`. |
| `getDistinctId()` | User ID when identified; otherwise the anonymous ID. |
| `getSessionId()` | Current session ID. |
Use `alias(newId, previousId)` only when both IDs belong to the same person. Use `reset()` for logout or account switching.
## Attribution
```ts theme={null}
const attribution = datalyr.getAttribution()
const journey = datalyr.getJourney()
```
The SDK captures supported click IDs, UTM parameters, and referrer data. URL values are redacted before collection when they contain known sensitive parameters.
You can also set known attribution manually:
```ts theme={null}
datalyr.setAttribution({
utm_source: 'partner',
utm_campaign: 'spring_launch'
})
```
## Checkout metadata
Use the SDK helpers when creating a checkout on your server:
```ts theme={null}
const stripe = datalyr.getStripeMetadata()
const whop = datalyr.getWhopCheckoutMetadata()
```
These helpers return the current visitor identity in the shape expected by the supported checkout flow.
## Super properties
Super properties are added to every later event:
```ts theme={null}
datalyr.setSuperProperties({ app_version: '2.4.0' })
datalyr.unsetSuperProperty('app_version')
```
## Lifecycle
```ts theme={null}
await datalyr.flush()
datalyr.destroy()
```
`flush()` sends queued events. `destroy()` removes listeners and stops the SDK; only use it when the integration is being torn down permanently.
# Conversion not delivered
Source: https://docs.datalyr.com/troubleshooting/conversion-delivery
Find whether collection, rule matching, or the destination failed.
Fix the first failing stage. Sending more test events does not help when the event never matches a rule or the destination asset is wrong.
## 1. Was the event collected?
Open **Events** and find the exact source event. Check its name, source, timestamp, workspace, value, currency, and identifiers.
If it is missing, stop here and fix collection or the revenue source.
## 2. Did a rule match?
Open **Conversions** and confirm the rule is enabled. Compare its event name and every filter with the collected event. Check whether the rule expects web, server, app, or a specific source.
If no delivery attempt exists, the rule did not match or was disabled at processing time.
## 3. Is the destination correct?
* Meta, Google, and TikTok use the primary account selected in **Sources**.
* Snapchat uses the Pixel ID or App ID saved on the rule.
* OpenAI Ads uses the connected Pixel ID and key.
Confirm the destination belongs to the campaigns you intend to optimize.
## 4. Read the delivery result
An error response usually identifies invalid credentials, missing required fields, an unsupported destination event, or an invalid asset. Correct that field, then send one new controlled event.
An accepted response means the platform received the request. The platform can still deduplicate, delay, reject attribution, or omit it from a campaign report according to its own rules.
## 5. Check match quality inputs
Preserve reliable customer identifiers, click IDs, event time, transaction or event ID, value, currency, IP address, and user agent when applicable and permitted. Missing match inputs may reduce attribution even when delivery succeeds.
When escalating, include the Datalyr event ID, rule, destination, delivery timestamp, status, and sanitized error. Never include full API credentials.
# Different numbers
Source: https://docs.datalyr.com/troubleshooting/data-differences
Compare Datalyr with an ad, revenue, or analytics platform.
Two dashboards can be internally correct while answering different questions. Compare definitions before totals.
## Make the reports comparable
Match all of these:
1. date range and timezone
2. currency
3. gross versus net revenue
4. refunds, chargebacks, tax, and shipping treatment
5. event date versus click or processing date
6. attribution model and lookback window
7. included accounts, campaigns, and environments
Ad platforms may each claim the same conversion inside their own attribution windows. Datalyr follows the journey and reporting rules configured in Datalyr, so its attributed total should not be expected to equal the sum of every platform's claims.
## Narrow the comparison
Start with one transaction, one campaign, and one day.
* **Transaction differs:** compare amount, currency, refund state, and timestamp.
* **Spend differs:** confirm the connected ad account and wait for finalized campaign data.
* **Conversion count differs:** compare event definitions, deduplication IDs, attribution windows, and view-through inclusion.
* **Today differs but older dates match:** allow for source sync and platform processing delay.
## Check time boundaries
A purchase near midnight can land on different days when systems use different timezones. A platform may also report a conversion on the ad interaction date while Datalyr shows it on the event date.
## Document the remaining gap
Record both report names, account IDs, filters, timezone, date range, metric definition, and one example record. A percentage difference without these inputs is not actionable.
Do not reconnect a healthy source to force two reports to agree. Reconnection cannot align different attribution or revenue definitions.
# Troubleshooting
Source: https://docs.datalyr.com/troubleshooting/index
Start at the first missing stage and follow one known record.
Most tracking problems become simple when you trace one event instead of comparing a large total.
## Choose the first broken stage
1. **Nothing reaches Datalyr:** start with **No events**.
2. **Activity arrives, but a purchase or subscription does not:** use **Missing revenue**.
3. **The conversion exists, but has no campaign journey:** use **Missing attribution**.
4. **A source card shows an error or stale state:** use **Integration errors**.
5. **Both systems have data, but totals disagree:** use **Different numbers**.
6. **The conversion exists but did not reach an ad platform:** use **Conversion not delivered**.
## Use a controlled test
Record the workspace, environment, event or transaction ID, source, timestamp with timezone, and expected result. Change one thing, repeat the test once, and check the same record through each stage.
Avoid reconnecting sources, rotating keys, or reinstalling SDKs before locating the failure. Those actions can create new variables or duplicate tracking.
## What to collect for support
* workspace name and public ID
* affected page, source, or SDK and version
* one event or transaction ID
* test timestamp and timezone
* exact error text or delivery status
* what you expected and where the record last appeared
Remove secrets, payment details, and sensitive customer data from screenshots and logs.
# Integration errors
Source: https://docs.datalyr.com/troubleshooting/integration-errors
Recover an authorization, credential, or configuration failure.
Open **Sources**, find the affected card, and identify its current state before changing anything.
## Needs configuration
Authorization succeeded, but setup is incomplete. For Meta, Google Ads, or TikTok, finish primary-account selection. Choose the final account used by the workspace, then save it.
## Authorization error
1. Confirm the authorizing person still has access in the provider.
2. Check whether an admin removed the app or changed required permissions.
3. Reconnect once and approve the requested access.
4. Select the required account after returning to Datalyr.
If no accounts appear, fix access in the provider first. Repeating OAuth with the same insufficient user will produce the same result.
## Credential error
For direct-key sources such as OpenAI Ads, copy a current credential and asset ID from the provider. Remove accidental spaces. If the key may have leaked, replace it at the provider, then update Datalyr.
## Connected but stale
Do not disconnect immediately. First verify:
* the selected account or asset
* a date range containing known activity
* the source's latest activity time
* provider-side webhook or sync health
* whether only one event or the whole source is missing
A healthy connection with one missing record is usually a transaction-level problem.
## Disconnect or retry deletion
Disconnect when you intentionally need to revoke access, replace the connected account, or rebuild a broken authorization. For Meta, Google, and TikTok, switching the primary account requires disconnecting and reconnecting and clears existing synced platform data.
If a source remains in deletion, use the available retry action. Avoid starting a second connection until cleanup finishes.
When escalating, include the workspace, provider, connection state, account or asset ID (not secret), last successful activity, and exact error text.
# Missing attribution
Source: https://docs.datalyr.com/troubleshooting/missing-attribution
Find where a campaign touchpoint stopped matching to a conversion.
Attribution needs three things: a captured campaign touchpoint, a preserved visitor journey, and a conversion that can be matched back to that journey.
## 1. Check the landing event
Open the visitor's first relevant `pageview`. Confirm the landing URL captured the expected UTM parameters or platform click ID. If the parameter is absent from the actual landing URL, Datalyr cannot recover it later.
If every paid visit is missing campaign data, review ad destination URLs, redirects, consent behavior, and tracking installation. Redirects must preserve query parameters.
## 2. Follow the identity
Check whether the anonymous visitor ID remains stable through the journey and whether the user is identified when known.
* A new ID after every page suggests storage or initialization problems.
* A domain change can break the journey without cross-domain tracking.
* A web-to-app handoff needs an explicit identity or campaign bridge.
* A hosted checkout needs supported metadata or customer matching.
## 3. Inspect the conversion
Confirm the revenue or conversion event contains a compatible visitor, user, customer, or transaction identity. An event can be collected correctly but remain unattributed when it cannot be joined to the earlier visitor.
## 4. Run a clean test
1. Open a private session with a unique UTM campaign.
2. Land on the final destination URL.
3. Complete the same cross-domain, checkout, or app path as a customer.
4. Trigger a test conversion.
5. Inspect the full journey in order.
Use a unique campaign value so the test is easy to find.
Successful delivery to an ad platform does not prove Datalyr has a complete journey. Delivery and attribution are separate stages.
# Missing revenue
Source: https://docs.datalyr.com/troubleshooting/missing-revenue
Trace one purchase, subscription, renewal, or refund into Datalyr.
Start with one transaction ID. Aggregate totals hide whether the problem is collection, filtering, duplication, or refund treatment.
## 1. Verify the source transaction
Confirm the transaction reached a final state in Shopify, Stripe, RevenueCat, Superwall, Whop, Checkout Champ, or your SDK. Record its ID, event type, amount, currency, and timestamp.
An authorization, incomplete checkout, test-mode payment, or pending transaction may not count as realized revenue.
## 2. Check the source
Open **Sources** and confirm the revenue source is connected. Review its recent-activity signal.
* **Connection error:** repair authorization, credentials, webhook, or required configuration.
* **Connection healthy but no recent activity:** check the provider-side webhook or integration setup.
* **Other transactions arrive:** investigate the missing transaction's status and payload instead of reconnecting.
## 3. Search Datalyr
Search **Events** using the transaction ID and a date range around the source timestamp. Compare:
* amount and currency
* event type
* source timestamp versus processing time
* customer or visitor identifiers
* test versus production environment
If the event exists but a dashboard total differs, the issue is reporting logic, date range, or refund treatment—not ingestion.
## 4. Check duplicates and adjustments
Datalyr may deduplicate repeated deliveries using a transaction or idempotency identifier. Refunds, chargebacks, cancellations, and subscription changes can reduce net revenue or appear as separate activity. Compare gross and net figures consistently.
## Escalate with evidence
Provide the source, transaction ID, event type, amount, currency, timestamp with timezone, and whether neighboring transactions arrived. Never send payment credentials or full API secrets.
# No events
Source: https://docs.datalyr.com/troubleshooting/no-events
Find why a website, server, or app is not sending activity.
Use one controlled test and follow it from the device to **Events**.
## 1. Confirm the test environment
* The latest code is deployed to the URL or app build you are testing.
* The installation uses the workspace ID or server key from the active workspace.
* You are looking at a date range that includes now.
* Browser privacy tools, content blockers, and consent settings are not suppressing the test.
Test in a clean private session with blockers disabled. Do not use production traffic as your first diagnostic.
## 2. Check the installation
For web tracking, load one page and inspect the browser console and network activity for a blocked script, content-security-policy error, or initialization error. Confirm Datalyr initializes once.
For server or mobile SDKs, enable the SDK's debug logging, send one simple event, then flush before the process exits or the app is closed.
## 3. Compare automatic and manual tracking
Send a simple manual event.
* **Manual and automatic events are missing:** initialization, credentials, consent, network access, or workspace routing is wrong.
* **Manual works, automatic does not:** review page or screen tracking configuration and framework lifecycle hooks.
* **Events appear only after a delay:** review queue and flush behavior, especially in serverless jobs and short-lived scripts.
## 4. Find it in Datalyr
Open **Events**, search for the exact event name, and widen the date range. Check the source and identifiers to make sure the event did not arrive under a different environment or workspace.
## Still missing
Capture the workspace ID prefix, SDK name and version, environment, event name, test timestamp with timezone, and the relevant debug error. Do not include a full secret API key.
Reinstalling repeatedly can create duplicate tracking. Change one thing at a time and remove abandoned snippets before retesting.
# Checkout funnels
Source: https://docs.datalyr.com/use-cases/checkout-funnels
Connect landing pages, checkout steps, upsells, rebills, and refunds in one customer journey.
Use this setup when the landing page and transaction system live on different domains, especially for CheckoutChamp funnels. The goal is to preserve the original acquisition context through checkout and report the full order lifecycle—not only the first payment.
## Before you start
You need access to the funnel pages, the checkout platform, and every domain customers visit. Decide which system is authoritative for orders, refunds, rebills, chargebacks, and cancellations.
## 1. Track the complete funnel
Install Datalyr on the first landing page and every editable funnel step. Track the few events that describe real progress, such as `offer_viewed`, `checkout_started`, and `upsell_accepted`. Keep names and properties consistent between funnel variants.
For CheckoutChamp, use the **Global Head Script** shown in **Sources → CheckoutChamp**. Do not add another Datalyr browser install to the same pages.
## 2. Preserve customer identity
The same visitor must survive transitions between landing, checkout, and upsell domains. Use the supported script or platform integration instead of copying browser identifiers into custom fields yourself. If customers sign in, identify them with the same stable account ID used elsewhere in your product.
## 3. Connect transaction events
For CheckoutChamp, create the Export Profiles provided by Datalyr for:
* Purchase
* Refund
* Chargeback
* Recurring payment
* Cancellation
Copy each URL from the source setup screen. These lifecycle events are what allow gross, refunded, and net revenue to remain accurate after the first order.
## 4. Test every branch
Run a test visit with UTMs or an ad click, then complete the base order and each upsell path. Confirm the original visit, funnel events, order value, currency, order ID, and products appear on one journey. Also generate a refund or cancellation and confirm reporting changes.
## Common problems
* **The order appears but has no acquisition source:** identity was lost during a domain transition, or tracking started after the landing page.
* **Revenue is duplicated:** two browser installations or duplicate transaction exports are active.
* **Net revenue never changes:** refund, chargeback, recurring, or cancellation profiles are missing.
* **An upsell has the wrong value:** the platform sent the full order total where an incremental amount was expected.
## You are done when
A test customer can move from the first campaign visit through checkout and an upsell, and Datalyr shows one journey with the correct net revenue after a lifecycle change.
See [CheckoutChamp revenue](/revenue/checkoutchamp) for the exact source configuration.
# Creators with Whop
Source: https://docs.datalyr.com/use-cases/creators-whop
Connect creator storefront visits, Whop checkouts, subscriptions, and revenue to acquisition.
Use this setup when customers discover an offer on your site and pay through Whop. It connects the content or campaign that created demand to the purchase and subscription events reported by Whop.
## Before you start
You need access to the landing site, Datalyr's Whop source, and the Whop business receiving payments. Choose the acquisition platforms you want to measure and the purchase event you will use for optimization.
## 1. Track the landing experience
Install [web tracking](/getting-started/install-web-tracking) on every page that can introduce or sell the offer. Verify a pageview before changing the checkout. Track meaningful steps such as offer views or checkout starts only when they help you answer a real funnel question.
## 2. Pass identity into Whop
When creating a supported checkout, use `getWhopCheckoutMetadata()` from the Web SDK and pass the returned values into the checkout flow. This creates the bridge between the anonymous visitor and the transaction Whop later reports.
Do not invent or cache your own visitor identifier. Request the metadata when the checkout begins so the current visitor is used.
## 3. Connect Whop revenue
Open **Sources → Whop**, complete the connection, and configure the webhook shown in the setup flow. Whop should remain the authority for purchases, recurring payments, refunds, and membership changes.
## 4. Connect acquisition platforms
Connect the ad accounts used to promote the offer. Create a conversion rule for the first successful purchase or another event that reflects your actual optimization goal. Avoid sending routine renewals as new-customer purchases unless that behavior is intentional.
## 5. Verify end to end
Open the landing page in a private window with test campaign parameters, proceed through checkout, and complete a test purchase. Confirm:
* The landing visit and checkout belong to the same journey
* The purchase has the correct value, currency, customer, and transaction ID
* The acquisition source is retained
* The selected ad destination receives the test conversion
* A refund or renewal updates the same customer when tested
## Common problems
* **Unattributed purchases:** checkout metadata was omitted or created before Datalyr initialized.
* **Visits are missing:** tracking is not installed on the first landing page or is blocked by consent configuration.
* **Duplicate revenue:** the same purchase is being sent by Whop and custom application code.
* **Wrong optimization counts:** recurring events are included in a new-customer conversion rule.
## You are done when
One test buyer has a continuous journey from campaign visit to Whop purchase, with correct revenue and a verified conversion in the intended destination.
See [Whop revenue](/revenue/whop) for connection and checkout metadata details.
# Health and wellness
Source: https://docs.datalyr.com/use-cases/health-wellness
Measure acquisition and revenue while reducing sensitive product context sent to ad platforms.
Use this setup for supplements, vitamins, wellness products, telehealth, and other health-adjacent businesses. It combines normal journey and revenue measurement with an outbound privacy safeguard for health-related catalog and page data.
Redaction is a technical safeguard, not a substitute for legal review, consent management, or the policies of each destination platform.
## 1. Establish the normal data flow
Install Datalyr on the website or Shopify store, connect the authoritative revenue source, and verify a test purchase before enabling redaction. Starting with a working flow makes it possible to distinguish privacy filtering from installation problems.
## 2. Connect only necessary destinations
Connect the ad platforms required for measurement or conversion delivery. Review what each conversion rule sends and avoid forwarding events or properties that have no clear purpose.
Health and wellness redaction currently applies to supported outbound events for Meta, TikTok, Google, and OpenAI Ads. Review other destinations independently.
## 3. Enable health redaction
Open **Settings → Privacy & redaction**, find **Health & Wellness**, and enable **Strip health-vertical fields**.
The safeguard removes or sanitizes product names, categories, content fields, and sensitive URL context that could reveal a condition, ingredient, or treatment. It preserves the fields needed for useful measurement, including value, currency, order ID, supported click IDs, and appropriately hashed customer matching data.
## 4. Test with realistic content
Use a test catalog item and URL that contain the kind of health context your real store uses. Complete a test conversion, then inspect the destination's test-event view. Confirm the sensitive product and page details are absent while the event name, value, currency, and matching signals remain.
Repeat this test after major catalog, theme, URL, or tracking changes.
## Common problems
* **Sensitive text still appears:** the event is reaching a destination not covered by the setting, or custom fields contain information outside the standard redaction set.
* **Matching quality drops:** required identity or click-ID fields were removed by separate custom logic.
* **The test event never arrives:** verify the base integration and conversion rule before diagnosing redaction.
* **Internal analytics lose useful detail:** apply destination-side safeguards deliberately; do not remove fields earlier in collection unless required.
## You are done when
A realistic test purchase is attributed correctly, the destination receives the value needed for measurement, and sensitive health-related product or page context is not present in the outbound payload.
See [Health and wellness redaction](/advanced/health-wellness-redaction) and [Privacy and redaction](/advanced/privacy) for field behavior and broader controls.
# Lead generation
Source: https://docs.datalyr.com/use-cases/lead-generation
Connect campaigns and form submissions to qualified leads, sales outcomes, and revenue.
Use this setup when the first conversion is a form, booked call, application, or demo request, but the real business outcome happens later. The goal is to measure the full path without treating every form submission as equal.
## Define the funnel first
Choose a small set of stages that correspond to actual business decisions. A common model is:
1. `lead_submitted`
2. `call_booked`
3. `lead_qualified`
4. `deal_won`
Use stable names and document what causes each event. Button clicks, form views, and validation errors should not masquerade as completed leads.
## 1. Track acquisition and submission
Install the Web SDK before paid traffic reaches the landing page. Send the lead event only after the form or booking platform confirms success—not when the submit button is clicked.
Include useful, non-sensitive properties such as form name, offer, or location when they help segment performance. Do not place raw personal or sensitive information in ordinary event properties.
## 2. Establish a stable identity
After the form creates a record, identify the visitor with your own durable lead, contact, or account ID. Use the same ID when later stages are reported from your application or backend. If email is used for supported matching, normalize it consistently and follow your consent and privacy requirements.
## 3. Report downstream outcomes
Send qualified-lead and closed-deal events from a trusted backend using the [Node SDK](/sdk-reference/node), or connect a supported revenue source when payment happens through Stripe, Shopify, Whop, or another available integration.
Include a stable event or transaction ID so retries do not create duplicates. For won revenue, include the final value and currency. Do not expose private server credentials in browser code.
## 4. Configure optimization deliberately
Connect the acquisition platforms and begin with the event that has enough volume and accurately represents success. As downstream data becomes reliable, move optimization from raw submissions toward qualified leads or won revenue.
## 5. Verify the complete path
Submit a test lead from a tagged private session, create the corresponding record, advance it through at least one downstream stage, and confirm all events appear on one journey in the correct order.
## Common problems
* **Too many leads:** the event fires on a click instead of confirmed success.
* **Later stages are unattributed:** the backend event lacks the stable ID established at submission.
* **Duplicate closed deals:** retries do not reuse the same event or transaction ID.
* **Ad platforms disagree with Datalyr:** compare the same stage, attribution window, timezone, and date basis.
## You are done when
A test lead can move from campaign click to a confirmed form submission and downstream outcome on one customer journey, and the chosen optimization event reaches the correct ad account.
# Mobile apps
Source: https://docs.datalyr.com/use-cases/mobile
Connect mobile acquisition, in-app behavior, subscriptions, and campaign conversions.
Use this setup for native iOS, React Native, or Expo apps. A complete mobile implementation joins campaign entry, app activity, a known customer identity, and subscription events from RevenueCat or Superwall.
## Before you start
List the platforms and environments you ship, the subscription provider you use, and the small number of app events that describe activation and purchase intent. Decide how a signed-in user is represented consistently across the app and subscription system.
## 1. Install and initialize the SDK
Use the [iOS SDK](/sdk-reference/ios) for Swift or the [React Native SDK](/sdk-reference/react-native) for React Native and Expo. Initialize once during application startup, before tracking screens or product events.
Keep development and production configuration separate. Verify events in a debug or sandbox build before releasing the integration.
## 2. Model the product journey
Track the screens and events that answer real product questions: onboarding completed, paywall viewed, trial started, or a core action completed. Keep names stable across releases and avoid sending an event for every UI interaction.
## 3. Identify signed-in users
Call `identify` after the app has a trusted user ID. Use that same durable identity in RevenueCat or Superwall where supported, and call `reset` on logout. This deterministic bridge is more reliable than attempting to infer that two devices or sessions belong to one person.
Do not use an email address or advertising identifier as your primary internal user ID. Respect App Tracking Transparency and your broader analytics consent requirements.
## 4. Connect subscription revenue
Connect **RevenueCat** or **Superwall** from **Sources** and configure the webhook displayed by Datalyr. Use the environment that matches the app build, then test a purchase or subscription lifecycle event.
The subscription provider should remain authoritative for trials, renewals, refunds, and cancellations. Avoid sending the same transaction independently from the app.
## 5. Configure campaign attribution
Set up the mechanisms required by the platforms you advertise on, such as supported deep links, Android install-referrer behavior, Apple Search Ads, or Apple SKAdNetwork. Connect only the destinations you use and follow their current privacy and campaign requirements.
## 6. Verify end to end
Use a fresh test installation and complete the actual journey: open or install, onboarding, sign-in, paywall, and sandbox purchase. Confirm the ordered screen events, identified customer, transaction value and currency, and subscription status appear together. Then verify the intended conversion through the destination's test flow when available.
## Common problems
* **Events begin too late:** the SDK initializes after the first screen or campaign handling.
* **One person appears as multiple users:** the app and subscription provider use different stable IDs.
* **Users merge after logout:** `reset` is not called before another account signs in.
* **Revenue is duplicated:** both the app and subscription provider send the transaction.
* **Sandbox purchases are missing:** the webhook or source is connected to a different project or environment.
## You are done when
A clean test install produces an ordered app journey, joins to the signed-in customer, receives one subscription event from the authoritative provider, and verifies the intended campaign conversion without duplicate revenue.
See [RevenueCat](/revenue/revenuecat), [Superwall](/revenue/superwall), and [Apple SKAdNetwork](/integrations/apple-skadnetwork) for provider-specific setup.
# Shopify
Source: https://docs.datalyr.com/use-cases/shopify
Connect storefront behavior, Shopify orders, refunds, ad spend, and conversion delivery.
Use this setup when Shopify is the source of truth for purchases. It connects the first campaign visit to product discovery, checkout, the completed order, and later refunds so reporting reflects net revenue.
## Before you start
You need permission to install apps, edit the active theme, and connect the ad accounts you use. Have Shopify's test-payment flow ready so you can verify the integration without relying on a live customer.
## 1. Connect the store
Open **Sources → Shopify** and enter the permanent `myshopify.com` domain—not a custom storefront domain. Complete OAuth, install the Datalyr Web Pixel, and enable the Datalyr App Embed in the active theme.
Both installations matter: the App Embed observes the editable storefront, while the Web Pixel covers supported Shopify checkout activity. Do not add an extra manual Datalyr snippet when the App Embed already owns browser tracking.
## 2. Verify product discovery
Open the storefront in a private window with test UTMs. Browse a product and begin checkout. In **Events**, confirm the first pageview contains the expected page URL and campaign properties, followed by the storefront events you expect.
If the first visit is missing, fix that before testing revenue. Attribution cannot reconstruct acquisition context that was never collected.
## 3. Verify an order
Complete a Shopify test order and confirm the purchase includes:
* Order or transaction ID
* Value and currency
* Customer identity when available
* Products or line items
* The earlier visitor journey
Then refund the order and confirm refunded and net revenue update. Shopify should be the only authority for these transaction events; do not also send the same purchase manually.
## 4. Connect acquisition platforms
Connect Meta, Google Ads, TikTok, Snapchat, or OpenAI Ads from **Sources** as needed. Select the correct account and asset, then create a conversion rule for the paid-order event. Use the destination's test-event mode when available before enabling production delivery.
## 5. Reconcile reporting
Compare Shopify and Datalyr with the same date range, timezone, currency, test-order policy, and refund basis. Small differences can come from whether a report uses order date, event date, or refund date.
## Common problems
* **Duplicate pageviews:** both the App Embed and a manual snippet are installed.
* **Checkout is visible but the landing visit is not:** the App Embed is disabled or blocked on the storefront.
* **The store will not connect:** a custom domain was entered instead of the permanent Shopify domain.
* **Purchases are duplicated:** Shopify and custom code both send the order.
* **Revenue differs after refunds:** the reports use different timezones or refund-date behavior.
## You are done when
A private test visit with campaign parameters leads to one Shopify order on the same journey, the correct conversion reaches the selected destination, and a refund updates net revenue without creating duplicate events.
See [Install on Shopify](/installation/shopify) and [Shopify revenue](/revenue/shopify) for detailed configuration.
# SaaS with Stripe
Source: https://docs.datalyr.com/use-cases/stripe
Connect acquisition and signup to Stripe subscriptions, invoices, refunds, and cancellations.
Use this setup for SaaS products where the marketing journey begins on the web and Stripe is the source of truth for payment. It links the first visit to account creation, checkout, the initial subscription, and recurring revenue.
## Before you start
You need access to the product's frontend and backend, the Stripe account used by the product, and a Stripe test environment. Decide which lifecycle event represents a new customer and whether trials or signups should also be sent as conversions.
## 1. Track the acquisition journey
Install [web tracking](/getting-started/install-web-tracking) before paid traffic reaches the pricing or signup pages. Verify a pageview with campaign properties, then track only the product milestones you use, such as signup completed or trial started.
## 2. Identify the account
After signup, identify the visitor with your stable application user ID:
```ts theme={null}
datalyr.identify(user.id, {
email: user.email,
plan: user.plan
})
```
Use the same internal ID across sessions and devices when it represents the same person. Call `reset()` on logout or account switching so the next user's events are not attached to the previous account.
## 3. Connect Stripe
Open **Sources → Stripe** and complete Stripe Apps OAuth for the correct account. This connection supplies the authoritative payment lifecycle; a separate manual Stripe webhook is not required for the standard integration.
## 4. Bridge the visitor into checkout
Call `datalyr.getStripeMetadata()` when checkout begins:
* For Checkout Sessions, pass the returned `client_reference_id` and metadata.
* For PaymentIntents and Subscriptions, include `metadata.visitor_id` when the server creates the object.
* Supported Stripe Payment Links on `buy.stripe.com` can be decorated by the current Web SDK when that feature is enabled.
Create payment objects on the backend. Never expose a Stripe secret or private Datalyr credential in browser code.
## 5. Verify the lifecycle
Complete a Stripe test checkout and confirm the first visit, signup, checkout, and payment appear on the same customer journey. Check value, currency, Stripe customer ID, and transaction or subscription identifiers. Then test a renewal, refund, or cancellation and confirm it remains associated with that customer.
## 6. Configure conversions
Connect the acquisition platforms and create separate rules only for lifecycle events you intentionally optimize toward. A signup, trial, and first paid subscription answer different questions. Do not report every recurring invoice as a new-customer conversion unless that is explicitly desired.
## Common problems
* **The payment is unattributed:** visitor metadata was omitted when the Stripe object was created.
* **The wrong customer is attached:** identity was not reset during account switching.
* **Payment Links lose attribution:** the link was rendered before the SDK initialized or uses an unsupported flow.
* **New customers are overcounted:** renewal invoices are included in the acquisition conversion rule.
* **Test payments are absent:** the connected Stripe account or environment does not match the test.
## You are done when
A new user can arrive from a tagged campaign, sign up, complete a Stripe test checkout, and generate a correctly attributed first payment. A later lifecycle event stays on the same customer without being counted as another acquisition.
See [Stripe revenue](/revenue/stripe) for Checkout Sessions, PaymentIntents, Subscriptions, and Payment Links.