Web (JavaScript)
One script tag for any website
The browser SDK is a single file with no dependencies, about 5 KB minified. Every api serves it at /sdk/v1/iforevents.min.js: https://api.iforevents.com/sdk/v1/iforevents.min.js on IForevents Cloud, your own origin on a self-hosted install (see Self-hosting below). It needs the public project key only.
Install
Paste before </body>; the data- attributes initialize the client as soon as the file loads, and calls pushed to window.iforevents before that are replayed:
<script src="https://api.iforevents.com/sdk/v1/iforevents.min.js" async
data-project-key="<project key>"></script>
<script>
window.iforevents = window.iforevents || [];
window.iforevents.push(['track', 'signup_clicked', { plan: 'pro' }]);
</script>Attributes: data-project-key (required), data-base-url (the api origin events go to, default https://api.iforevents.com), data-auto-track="false" to disable automatic page views, data-debug="true" to log requests. The dashboard shows this snippet with your key and URLs filled in under Projects.
Without attributes, initialize by hand once the script has loaded:
<script src="https://api.iforevents.com/sdk/v1/iforevents.min.js"></script>
<script>
Iforevents.init('<project key>', { autoTrack: true });
Iforevents.track('signup_clicked', { plan: 'pro' });
</script>API
| Call | What it does |
|---|---|
Iforevents.init(key, options) | Creates the client (baseUrl, flushInterval ms, batchSize, autoTrack, debug). |
Iforevents.track(name, properties) | Queues an event; the queue flushes at batchSize (20) events or after flushInterval (10 s), and on pagehide. |
Iforevents.page(properties) | Queues a page view with page, url, referrer and title. Automatic with autoTrack, including pushState navigations. |
Iforevents.identify(customId, traits) | Attributes this and later events to customId (your id for the person) and stores email, name, phone_number and custom traits on the profile. Returns a promise. |
Iforevents.flush() | Sends the queue now. |
Iforevents.reset() | Forgets the identified user and starts a new anonymous one, for example on logout. |
Iforevents.userId() | The id events are currently attributed to. |
Every call is also available through window.iforevents.push([method, ...args]), which works before and after the script has loaded.
Elements with a data-iftrack="event_name" attribute track that event on click when autoTrack is on.
Users and privacy
On first load the SDK generates a random anonymous id (anon_...), keeps it in localStorage (iforevents_user_id) so later sessions belong to the same visitor, and sends it as X-User-Id on every request. identify replaces it with the id you give. Nothing else is stored, no cookies are set, and the only server contacted is the api at data-base-url. Calling reset() on logout keeps two people on one browser apart.
Events sent under the anonymous id are not merged into the identified profile: what a visitor did before signing up stays on the anonymous id. Pass the anonymous id (Iforevents.userId()) to your backend if it tracks server side for the same visitor, so both ends name the same person.
Errors
Requests that fail for a transient reason (network, 5xx, rate limit) stay queued for the next flush. A refused project key (401) or an exhausted monthly quota (429 quota_exceeded) drops the affected events: retrying would fail the same way. With debug: true failures are logged to the console.
Self-hosting
Load the script from your own api and point data-base-url (or baseUrl) at the same origin; nothing on the page talks to iforevents.com:
<script src="https://analytics.example.org/sdk/v1/iforevents.min.js" async
data-project-key="<project key>" data-base-url="https://analytics.example.org"></script>The api serves /sdk/v1/iforevents.min.js (and the readable iforevents.js) from the release it ships with, cached for an hour and revalidated by ETag. The ingest routes allow any origin without credentials, so no CORS configuration is needed on your side. Behind the Caddy overlay /sdk/* is already routed to the api; with your own proxy, forward it like /v1/*.