Insights and campaigns

Insights combines storefront events with server-side cart, checkout, and purchase events. Administrative routes require an admin session and a selected tenant; no current scoped API token grants general Insights access.

Install the storefront script

Read GET /api/admin/insights/settings. It returns einstellungen, shop_url, hosts, tenant_id, snippet, and api. Insert the returned script snippet into the storefront once. Its URL has the form /store/insights/sf.js?shop=<tenant-id> on the configured public API host.

The script and collection routes use /store/insights, without /api. They are exposed by the combined API and the shop/shop-admin split backends, not by the checkout-only split backend. Script loading uses the public tenant identifier, not an admin token.

The script tracks page navigation and supported catalog interactions, including SPA history/hash changes. Collection uses POST /store/insights/collect. A 204 response means the request was handled, not that every event was accepted; invalid or disallowed-origin events can also receive 204.

Settings and consent

Update configuration with PUT /api/admin/insights/settings. Options include:

URL patterns support {shop}, {slug}, {id}, {q}, {make}, {model}, and {year} where relevant. Set these to your storefront's routes before generating campaign destinations.

When consent_required is enabled, connect the consent banner to the script. After initialization:

window.sellforge.consent(true)  // Customer enabled tracking.
window.sellforge.consent(false) // Customer withdrew tracking consent.

Calling consent(false) clears the script's visitor, session, and campaign cookies and pending event buffers. An external storefront must explicitly integrate this signal; a cookie with a similar name does not automatically configure Insights.

Additional storefront events

After the script is ready, supported helpers include:

window.sellforge.search('workshop shirt', 12)
window.sellforge.track('wishlist_add', { product: 'prod_example' })
window.sellforge.vehicle('make-slug', 'model-slug', 2024)

window.sellforge.visitor() returns the current visitor ID; window.sellforge.campaign() returns the campaign code when set.

The script attaches X-SF-Visitor, X-SF-Session, and X-SF-Campaign to fetch/XHR requests targeting its configured API origin. If your storefront calls another host or proxies commerce requests through its own backend, preserve this attribution context when forwarding the request. The visitor/session values come from the script's sf_vid and sf_sid cookies; the campaign code comes from sf_cmp.

These values are attribution data, not authentication. Preserve UTM parameters and sfc/sfn through storefront redirects so the script can attribute the landing. Server-generated purchases and recurring billing remain the source for revenue events.

Read reports

The following GET endpoints use /api/admin/insights:

Historical reports generally accept from and to as YYYY-MM-DD and optional channel. The default range is 30 days and the maximum requested range is approximately three years; date boundaries use the Europe/Vienna reporting context. Online/live views have their own current-activity scope. Follow each response's field names rather than assuming a paginated items envelope.

Advertising campaigns

Campaign administration uses /api/admin/ad-campaigns:

• GET /meta supplies platform IDs and target types.
• POST /preview resolves a proposed target.
• GET/POST on the collection list/create campaigns.
• GET/PATCH/DELETE /:id read, update, or remove a campaign.
• POST /:id/duplicate copies it with a new tracking code.
• GET /:id/report reads attributed results.

Creation requires name, platform, and target_type, plus the appropriate target_id, target_query, or target_url. Optional fields include UTM overrides, budget_cents, start/end dates, status, and notes. List responses use kampagnen, and individual responses use kampagne.

Use the returned tracking URLs. Public short links use /store/r/:code and redirect to the configured destination with campaign/UTM parameters. Deleting a campaign with clicks archives it to preserve reporting; archived short links still redirect but no longer attach attribution parameters.