Create an installation
- Open Settings → SDK Events in your Sagepilot workspace.
- Select New installation, enter a name, and choose a platform.
- Web. In Allowed website origins, enter one origin per line, such as
https://shop.example.com. Include the scheme and any non-default port. Add the origin you will use for testing and use HTTPS in production. - Android or iOS. Set App identifier to the Android application ID or iOS bundle identifier. Create one installation per platform.
- Web. In Allowed website origins, enter one origin per line, such as
- Turn on Installation enabled and Event collection permitted, then click Save installation.
- Copy the Installation key, which has the format
workspace_id:installation_id. You can include this key in your website or app code.
Choose your API host
SetapiHost to the origin where you sign in to your Sagepilot workspace. The SDK gets its event upload URL when it starts a session.
Install the SDK
Install the latest published Event SDK for your platform. The commands use@latest so you get the current release when you install or upgrade.
Replace each example key with the installation key for that platform. The examples use the India API host. For a European workspace, replace it with https://eu.sagepilot.ai.
- Web with npm
- Web with a script
- React Native
Install the web events add-on.Save this as Import
sagepilot-events.ts and import it once from your browser entry point. If your framework renders on the server, load the module in a browser-only startup hook such as a React effect.setSagepilotAnalyticsAllowed where your site reads analytics permission. Call it with the current decision when your consent manager is ready and again whenever the decision changes.collectionEnabled when you create the SDK. Use false while the decision is unknown.
Verify the install
Open the registered test site or a fresh native build and grant analytics permission. If you need a web test control, add this to your test page before the startup code runs. Both web examples connect it to the SDK.Button from react-native and setSagepilotAnalyticsAllowed from your startup module. Add this to a test screen.
- Web. In your browser’s Network tab, check that the request ending in
/sdk/sessionssucceeds. For the npm install,events.diagnostics().enabledshould betrueafter you grant permission. - React Native. After you grant permission, check that
(await (await eventsReady).diagnostics()).enabledistruein your test build.
Discover and publish events
- In Settings → SDK Events, select your installation.
- Under Event mappings, set Discovery hours and click Start discovery.
- With analytics permission enabled, perform the actions you want to track during the discovery window. For an add-to-cart mapping, complete a cart addition and browse a product without adding it. Collect a matching sample for each rule you want to publish and an action that should match none of those rules.
- Click Refresh and check that the sample count increases. Click Generate AI proposal while the samples are available.
- Review the proposed names and leave the rules you want enabled. If you change any rules or toggle them, click Save rules. Click Validate rules, then Publish mapping when validation passes.
- Check that Event mappings shows Serving version followed by the version you published.
Verify a web event in a customer journey
Use a test workspace and an email address you control. You need permission to create and publish journeys.- Publish a website popup with Verify email with a code selected.
- In Engage → Journeys, click Create journey and name it. Choose your published event from the Sdk source as the trigger. Under Steps, add a one-minute Wait step. Review the setup and click Publish journey.
- Open the test storefront on a page that matches the popup’s display rules. Grant analytics permission, submit your test email, and enter the verification code.
- In the same browser, perform the mapped action again. Open the verified test customer’s profile in Sagepilot. Check that the event appears in the timeline and that the customer entered the test journey.
Optional website settings
Publish a website popup
- In Settings → SDK Events, select your web installation. Under Website popup, click Edit popup.
- Under Content & form, choose the contact fields. For a customer journey, set Identity verification to Verify email with a code. The built-in form records marketing opt-in on submission. Make that clear in your popup copy.
- Use Design to adjust the popup’s appearance and preview it on desktop and mobile.
- Open Display rules, turn on Enable popup, and choose where and when the popup should appear.
- Click Save popup draft, then Publish popup. Test on a page that matches the display rules.
Remember returning browsers with a cookie
The standard install uses browser storage. To use a first-party visitor cookie, proxyPOST /sagepilot/visitor/WORKSPACE_ID/INSTALLATION_ID on the storefront to POST /platform-api/v1/sdk/visitors/WORKSPACE_ID/INSTALLATION_ID on your workspace’s API host.
Forward the original Origin, Sec-Fetch-Site, JSON body, and sagepilot_visitor cookie. Relay the response, including Set-Cookie and Cache-Control, to the browser. Keep other storefront cookies and credentials on the storefront.
In your web installation, turn on First-party visitor cookie and click Save installation. Sagepilot uses it for browsers that allow analytics to recover their visitor ID and popup completion state.
Troubleshoot a missing event
- SDK startup returns 404. Check the API host in your snippet and reload your site or app.
- Discovery has no samples. Check that the installation and event collection are enabled, analytics permission is granted, and the web origin or app identifier matches the registration. Repeat the actions before the discovery window closes and click Refresh.
- The discovery window closed without usable samples. For a first test, create a new test installation and replace its key before starting discovery again. For a remap on a serving installation, contact Sagepilot Support with the installation name and draft version so you can keep the current mapping serving.
- An expected event is missing. Check that its rule is enabled and the mapping version is serving. Repeat the action and confirm it completed. A successful cart change is evidence for an add-to-cart event. A button click may only record click intent.
- A web customer did not enter the journey. Check that the journey is published with the matching trigger and that the customer completed email verification in the same browser before performing the action.
- The native module is unavailable. Install the iOS pods if applicable and rebuild the native app. On Expo, open the development build.