PHP SDK
Record onboarding steps
A step is a milestone in getting started with your plugin: an account connected, a first form published. Record it where it happens:
$insights->step('connected_account');
- The first time only. The SDK stores the moment the step first happened, by the site’s own clock, in your plugin’s option row. Later calls change nothing, so call it every time the milestone is reached; there is nothing to check first.
- Keys follow the feature-key rule:
^[a-z][a-z0-9_]{0,63}$. - 32 steps of your own per site, plus
activated. A snapshot carries at most 33. A 33rd new key of yours is refused. A key already recorded is never refused. activatedis reserved. The SDK records it itself, the first time, while the site holds no installation token (revokeConsent()deletes the steps, so a later grant on such a site records it anew, with a new time): before it first registers, or after the server refused its token and before it registers again. It is recorded when consent is granted or your plugin is activated with consent already granted. A site in that second window that re-grants consent or is re-activated getsactivatedtoo. A site that already registered before it updated to an SDK withstep()holds a token, so it does not getactivatedand does not appear as a new site in a funnel.- Nothing before consent. With consent off,
step()records nothing, not even locally.revokeConsent()deletes what was recorded. - A bad key,
activated, or a 33rd key of your own is refused and listed inerrors().step()never throws.
Every snapshot carries the whole map, so losing one snapshot loses nothing. For an owner who has not consented, on a site that holds no installation token (the same rule as activated), the preview shows the activated step that opting in would record, as it shows inventory to an undecided owner; steps already stored are kept, and activated is added after them only if it is not stored. A site that holds a token, or has already consented, previews exactly what it would send. A site with no step sends no steps field at all. Funnels are defined on the dashboard’s Funnels screen, from the steps your sites have reported.