Funnels

Track the journey a visitor takes through your funnel, with one script tag.

Define the steps in the dashboard, then add one script tag to every page you want counted. The script is a tracking beacon, not a widget - it renders nothing. Funnels whose pages were built for you from a template already carry it, so this guide is for pages on a website you host yourself.

Add the tracker

<script src="https://app.softsolz.uk/softsolz.js"
  data-public-key="pk_live_your_key"
  data-service-id="funnels"
  defer></script>

The public key only works on the web addresses you allow when you create it, so a copied key is useless elsewhere. Single-page apps are handled: the script notices when the address changes without a reload. A step set to Page address is ignores the domain, tracking tags and a trailing .html, so /pricing and /pricing.html count as the same page.

Count actions, not just pages

Set a step to Something happens and give it an event name. Send that event from your page once the tracker has loaded, and link a visitor to a contact when you know who they are.

Softsolz.funnel.track('added_to_basket')
Softsolz.funnel.identify('contact_id')

Try it before you ship: the Widget Tester has a Funnels mode with an example site, an event sender and a live log of what each request counted.

Track from your own code

If you would rather not use the script, post the page address yourself. Keep the visitor_token we return and send it back next time, so the same person is not counted twice.

curl -X POST https://app.softsolz.uk/api/funnels/track \
  -H "X-Softsolz-Public-Key: pk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"page_url":"https://your-site.com/pricing","visitor_token":"fv_..."}'

Create a funnel

A funnel needs a name of 1 to 200 characters and between 2 and 20 steps. It is active as soon as it is created. A name that is too long is refused rather than shortened, a field the endpoint does not know is refused with unknown_field, and every other mistake answers 400 with the field that caused it.

curl -X POST https://app.softsolz.uk/api/v1/services/funnels/funnels \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"name":"Free trial","steps":[{"name":"Pricing","match_value":"/pricing"},{"name":"Trial started","trigger_type":"event","trigger_value":"trial_started","is_goal":true}]}'

A funnel is active, paused (switched off but still holding its steps), draft (no steps yet) or archived. An event name may use letters, numbers, dots, colons, dashes and underscores. Event steps are read back with both trigger_value and match_value set to the event name.

Read the results

curl "https://app.softsolz.uk/api/v1/services/funnels/funnels/{funnel_id}/report?days=30" \
  -H "Authorization: Bearer sk_live_your_key"

days must be a whole number from 1 to 400; anything else answers 400 with days_out_of_range. Send from and to (YYYY-MM-DD) instead for fixed dates, and compare=true to add the period before.