Global Properties

Attach key-value metadata to every analytics event sent from a page. Unlike custom event properties, which are per-event, global properties persist across all events for the lifetime of the page.

Setting Initial Properties

If you have properties available at page load, set them directly on the script tag via data-global-properties. These are applied before the initial pageview, so the first event already carries them:

<script
  src="https://betterlytics.io/analytics.js"
  data-site-id="your-site-id"
  data-global-properties='{"plan":"premium","app_version":"2.1.0"}'
></script>

The attribute value must be a valid JSON object. Invalid JSON is logged to the console and ignored.

Setting Global Properties

Call setGlobalProperties() once your app has the data available:

betterlytics.setGlobalProperties({
  plan: "premium",
  app_version: "2.1.0",
  environment: "production",
});

All subsequent events will include these properties automatically.

Calling setGlobalProperties() again merges the new properties with existing ones. To clear all properties, use clearGlobalProperties(). You can read the current properties with getGlobalProperties().

betterlytics.setGlobalProperties({ plan: "premium" });
betterlytics.setGlobalProperties({ app_version: "2.1.0" });
betterlytics.getGlobalProperties(); // { plan: "premium", app_version: "2.1.0" }
 
betterlytics.clearGlobalProperties();
betterlytics.getGlobalProperties(); // {}

Accepted Values

Values must be strings, numbers, or booleans.

betterlytics.setGlobalProperties({
  plan: "premium",       // string ✓
  seats: 5,              // number ✓
  active: true,          // boolean ✓
});

Global properties with the following values are ignored and not included in events:

betterlytics.setGlobalProperties({
  data: { nested: true },  // objects ✗
  tags: ["a", "b"],        // arrays ✗
  missing: null,           // null ✗
  broken: undefined,       // undefined ✗
  bad: Infinity,           // non-finite numbers ✗
  worse: NaN,              // non-finite numbers ✗
});

What to track

Global properties are designed for categorical, non-personal attributes that describe the context of a visit. Not the identity of a person.

Good candidates:

• Subscription plan or tier (plan: "pro")
• User role (role: "admin")
• App or release version (app_version: "2.1.0")
• Feature flag state (new_checkout: true)
• Environment (environment: "production")
• Experiment cohort (experiment: "variant-b")

Avoid storing personally identifiable information (PII) such as user IDs, email addresses, or names. Property values are stored in your analytics data, appear in dashboard filter suggestions, and are visible to anyone with dashboard access.

Limits

Values outside these bounds are sanitized server-side without rejecting the event. The rest of the properties still go through, and the event itself is never dropped because of a bad global property.

Filtering in the Dashboard

Once events with global properties are collected, they appear in the filter dropdown under Global Properties. Select a property key to filter all dashboard views by its values.

Global property filters work at the session level. A session is included if the property matched at any point during that visit, and all of its metrics count in full. See Global property filters for a full explanation of what this means for your metrics.