Home/Privacy & Consent/Cookie Consent

Cookie Consent

The consent API is ZipTier's general-purpose way to report a visitor's cookie or tracking consent choice. It's a single call carrying one key per category, so it isn't tied to any one feature. Today the analytics category gates Visitor Analytics — nothing is collected for it, and no identifier is stored for it, until consent is granted. More categories will be added as keys on this same call as further features come under it.

Where it lives: The consent API is published by the ZipTier widget script itself the instant it loads on your page, so there's nothing extra to embed.

The Consent API

Report a visitor's consent choice by calling:

window.ziptierConsent({ analytics: 'granted' | 'denied' });

This is available the instant the ZipTier widget script has loaded. analytics is the only category live today, gating Visitor Analytics collection (see the worked example below); more categories will appear as new keys on this same call as they ship. Anything other than the literal string 'granted' on a given category, including a typo or an unexpected value, is treated as 'denied', so a malformed call always fails closed rather than open.

Calling it with 'denied' after a prior 'granted' clears the visitor's locally stored id for that category and stops collection for the rest of that page session. A later 'granted' call resumes cleanly.

If Your CMP Loads Before Our Script

A cookie-consent platform (CMP) can fire its own consent event before the ZipTier widget script has finished loading. Push to a queue instead of calling the function directly, and it will be drained automatically, in order, the moment the widget is ready:

(window.ziptierConsentQueue = window.ziptierConsentQueue || [])
  .push({ analytics: 'granted' });

This queue pattern is always safe to use, even if you're not sure whether the widget script has loaded yet. Push to it and forget it.

Example: Visitor Analytics

Visitor Analytics is the first feature built on this consent signal (see the Visitor Analytics guide). It's gated behind two independent switches: the account-wide Settings > Analytics > Visitor Analytics toggle, and the analytics category on this consent API. Both must allow collection; the widget itself keeps working either way, only the analytics collection is gated.

Default Consent by Country

Settings > Analytics also offers an optional Default Consent by Country control, letting you set a default for visitors who haven't made a choice yet. This is only ever a fallback: an explicit window.ziptierConsent(...) call, from your own banner or a CMP, always overrides it, whenever it arrives, including after collection has already started under the default.

If you don't configure this, ZipTier applies its own default: visitors in the EU/EEA, the UK, Norway, Iceland, Liechtenstein and the United States default to denied, and visitors everywhere else default to granted. Configuring your own country list replaces that default entirely — the countries you list get the default you pick, and every other country gets the opposite.

Worked Example: Your Own Cookie Banner

A simple in-house banner with an Accept/Decline choice for an "Analytics" category reports it the same way on every relevant action: initial load (reflecting a saved or default preference), Accept All, and Save Preferences:

function reportAnalyticsConsent(analyticsAccepted) {
  window.ziptierConsent({ analytics: analyticsAccepted ? 'granted' : 'denied' });
}

// On initial load, once you know the visitor's saved or default preference:
reportAnalyticsConsent(savedPreferences.analytics);

// When the visitor clicks "Accept All":
reportAnalyticsConsent(true);

// When the visitor saves custom preferences:
reportAnalyticsConsent(preferences.analytics);

Worked Example: A Third-Party CMP

Most CMPs (OneTrust, Cookiebot, and similar) expose their own callback that fires whenever the visitor's consent choice changes. The integration is a few lines translating that platform's own analytics/performance category into a window.ziptierConsent(...) call:

// Example shape: adapt to your CMP's actual callback API.
YourCMP.onConsentChanged(function (consent) {
  var analyticsGranted = consent.categories.analytics === 'granted';
  (window.ziptierConsentQueue = window.ziptierConsentQueue || [])
    .push({ analytics: analyticsGranted ? 'granted' : 'denied' });
});

Always call the consent API directly rather than relying on your CMP's own script-blocking behavior to withhold collection. ZipTier's own gates are what actually control it, so a call is what registers your visitor's choice with us either way.

Troubleshooting

If visitor counts aren't changing after you call window.ziptierConsent(...), check that the widget script has actually loaded on the page, that you're using the exact key analytics (not, for example, analytics_storage), and that Visitor Analytics is also turned on under Settings > Analytics. As with the rest of Visitor Analytics, only production, on-site widget traffic is counted; sandbox testing and standalone full-page assistants never appear in these numbers.