picked 0.0.101-next.2 → 0.0.101

package/docs/reference/sdk/fields.md

@@ -0,0 +1,255 @@
+---
+type: reference
+layout: docs
+---
+
+# Fields
+
+Define your fields in code with `createField()`. Check the input with JSON Logic.
+Read the values that a user sends through the step context.
+
+## Define a field
+
+Define a field with `createField()` from the
+`@picked/client/plugins/create-experience` package. Each field needs a unique
+identifier, a name, a type, a label, and a count of the values that it takes:
+
+```ts
+import { createField } from '@picked/client/plugins/create-experience'
+
+// A text input that the user must fill in.
+export const emailField = createField({
+  id: 'email-address',
+  name: 'email-address',
+  type: 'text',
+  label: 'Email Address',
+  multiple: false,
+  required: true,
+  placeholder: 'you@example.com',
+})
+
+// A dropdown that takes more than one choice, with fixed options.
+export const communicationMethods = createField({
+  id: 'communication-methods',
+  name: 'communication-methods',
+  type: 'text',
+  label: 'Preferred contact methods',
+  multiple: true,
+  required: true,
+  options: [
+    {
+      id: 'email',
+      label: 'Email',
+      value: 'email',
+    },
+    {
+      id: 'phone',
+      label: 'Phone',
+      value: 'phone',
+    },
+    {
+      id: 'sms',
+      label: 'SMS',
+      value: 'sms',
+    },
+  ],
+})
+```
+
+## Register fields on the client
+
+Register fields when you create the Picked client. Pass a `fields` object. The key of an
+entry becomes the field `key` when the definition does not set one. A definition with its
+own `key` keeps it. Pass a function to build a definition once during the client setup:
+
+```ts
+import { createClient } from 'picked'
+
+const client = createClient({
+  projectId: 'your-project-id',
+  fields: {
+    email: {
+      id: 'email',
+      name: 'email',
+      label: 'Email Address',
+      type: 'text',
+      multiple: false,
+      required: true,
+    },
+    age: () => ({
+      id: 'age',
+      name: 'age',
+      label: 'Age',
+      type: 'number',
+      multiple: false,
+      required: false,
+    }),
+  },
+})
+```
+
+## Field types
+
+A field has one of four basic types: `text`, `number`, `boolean`, or `object`.
+
+```ts
+// One text input.
+const nameField = createField({
+  type: 'text',
+  multiple: false,
+  // ...
+})
+```
+
+Give an `options` array to let the user choose more than one value:
+
+```ts
+const nameField = createField({
+  type: 'text',
+  multiple: true,
+  options: [
+    {
+      id: 'option-one',
+      label: 'Option One',
+      value: 'product-id-one',
+    },
+    {
+      id: 'option-two',
+      label: 'Option Two',
+      value: 'product-id-two',
+    },
+    {
+      id: 'option-three',
+      label: 'Option Three',
+      value: 'product-id-three',
+    },
+  ],
+})
+```
+
+## Conditions
+
+A field and a field option both work with condition logic:
+
+```ts
+const conditionalField = createField({
+  id: 'conditional-field',
+  type: 'text',
+  condition: {
+    invoke: {
+      var: 'responses.has-answered-question',
+    },
+  },
+  options: [
+    {
+      id: 'conditional-option',
+      label: 'Conditional Label',
+      condition: {
+        invoke: {
+          var: 'responses.eligible-for-option',
+        },
+      },
+    },
+  ],
+})
+```
+
+## Field policies
+
+A field captures nothing until you permit it. Use a privacy policy to let Picked track
+or store the data of a field:
+
+```ts
+const colourField = createField({
+  id: 'favourite-colour',
+  name: 'favourite-colour',
+  type: 'text',
+  label: 'Favourite colour',
+  multiple: false,
+  required: true,
+  policies: {
+    trackValue: true, // Send the value to analytics.
+    storeValue: true, // Keep the value in browser storage.
+  },
+})
+```
+
+**Privacy policies**:
+
+- `trackValue`: set it to `true` to put the value of the field in your analytics events.
+  At `false`, and when the policy is absent, the events carry the field ID only.
+- `storeValue`: set it to `true` to let the SDK put the value in browser storage. At
+  `false`, and when the policy is absent, the SDK keeps the value out of storage.
+
+Both policies keep the value in the browser by default. A field with no `policies`
+object sends no value to your analytics and writes no value to browser storage. Keep
+the default for sensitive data such as a tax number, a credit card number, or a
+password. That data stays in the browser:
+
+```ts
+const sensitiveField = createField({
+  id: 'ssn',
+  name: 'ssn',
+  type: 'text',
+  label: 'Social Security Number',
+  multiple: false,
+  required: true,
+})
+```
+
+Neither policy stops the flow from the use of the value inside the page. A field that
+captures nothing still holds its value there, for step validation and for the conditions
+after the step. The policies control what leaves the page: your analytics, and browser
+storage.
+
+## Field metadata
+
+Add more text to help the user:
+
+```ts
+const passwordField = createField({
+  id: 'password',
+  name: 'password',
+  type: 'text',
+  label: 'Password',
+  multiple: false,
+  required: true,
+  placeholder: 'Enter a strong password',
+  description: 'Your password must be at least 8 characters',
+  helpText: 'Use a mix of letters, numbers, and symbols for better security',
+})
+```
+
+**Metadata fields**:
+
+- `placeholder`: the hint text that an empty input shows.
+- `description`: a short explanation below the label.
+- `helpText`: more guidance, or the requirements, next to the field.
+
+## Read a field value
+
+The SDK stores each field response in the experience state. Read a response through
+the `responses` object:
+
+:::code-group
+
+```ts [In Conditions]
+// Point at the value from a later field condition.
+const sensitiveField = createField({
+  condition: {
+    '==': [
+      {
+        var: 'responses.field-name',
+      },
+      'expected-value',
+    ],
+  },
+})
+```
+
+:::
+
+## Related
+
+- [How to validate a field](/how-to/validate-a-field)
+- [Fields](/reference/dashboard/fields) — the dashboard privacy controls.

package/docs/reference/sdk/index.md

@@ -0,0 +1,68 @@
+---
+type: reference
+layout: docs
+---
+
+# Picked SDK
+
+The Picked SDK lets you add a dynamic, personalized experience to your web
+application with very little code.
+
+:::tip
+The SDK is framework-agnostic. It works with React, Svelte, Vue, and plain
+JavaScript.
+:::
+
+## Precondition and condition
+
+| Category     | Question               | Description                                                                                   |
+| ------------ | ---------------------- | --------------------------------------------------------------------------------------------- |
+| Precondition | Must Picked start?     | Use it to check the environment, to filter by page, or for a feature flag that turns the SDK off completely. |
+| Condition    | Is this user eligible? | Use it to divide your users into groups, to enter a user into an A/B test, or to reach one group of users. |
+
+```ts
+const picked = createClient({
+  precondition: {
+    and: [
+      {
+        or: [
+          {
+            invoke: {
+              var: 'features.aa-test',
+            },
+          },
+          true,
+        ],
+      },
+      { invoke: { var: 'predicates.shopify-is-product-page' } },
+    ],
+  },
+  condition: {
+    invoke: {
+      var: 'features.convincely-enabled',
+    },
+  },
+  // The rest of the Picked options go here.
+})
+```
+
+:::warning
+A precondition or a condition that points at a feature flag reads the bucket of that
+feature flag. That read allocates the visitor at that moment.
+
+A precondition runs at startup. Picked therefore allocates every visitor to a feature
+flag that a precondition points at, before anything else happens. This includes a
+visitor who never reaches the experience that the feature flag controls.
+
+See [Allocation and exposure](/explanation/feature-flag-allocation) before you point a
+precondition at a flag.
+:::
+
+See [conditions](/reference/sdk/conditions) for more detail.
+
+## Related
+
+- [How to install the SDK](/how-to/install-the-sdk)
+- [How to register a component](/how-to/register-a-component)
+- [About conditions and the logic engine](/explanation/conditions-and-the-logic-engine) —
+  what the difference is between a precondition and a condition.

package/docs/reference/sdk/plugins/create-experience.md

@@ -0,0 +1,123 @@
+---
+type: reference
+layout: docs
+---
+
+# Create Experience Plugin
+
+This plugin registers an array of experiences on the Picked client.
+
+## Define a step
+
+Define a step with `createStep()`. Add it directly to an experience with
+`experience.addStep()`.
+
+```ts
+import { createExperience, createStep } from '@picked/client/plugins/create-experience'
+
+// Define the steps on their own.
+const welcomeStep = createStep({
+  id: 'welcome',
+  name: 'Welcome',
+})
+
+const contactStep = createStep({
+  id: 'contact',
+  name: 'Contact Details',
+})
+
+// Define the experience, then add the steps to build the flow.
+const onboardingExperience = createExperience({
+  id: 'onboarding',
+  name: 'User Onboarding',
+  targets: [{ selector: 'body', placement: 'after' }],
+})
+
+onboardingExperience.addStep(welcomeStep)
+onboardingExperience.addStep(contactStep)
+```
+
+Each step needs a `name`, and your analytics events use that name to identify the
+step. An `id` is optional. Picked makes one for you when you give none.
+
+You can use the same step on more than one experience.
+
+### Add a field to a step
+
+Define a field with `createField()`.
+
+```ts
+import { createStep, createField } from '@picked/client/plugins/create-experience'
+
+const emailField = createField({
+  id: 'email-address',
+  name: 'email-address',
+  type: 'text',
+  label: 'Email Address',
+  multiple: false,
+  required: true,
+  placeholder: 'you@example.com',
+})
+```
+
+Add a field to a step with `step.addField()`. You can also pass an array of
+`fieldIds` when you create the step:
+
+```ts
+const contactStep = createStep({
+  id: 'contact',
+  label: 'Contact Details',
+})
+
+contactStep.addField(emailField)
+
+// Or:
+
+const contactStep = createStep({
+  id: 'contact',
+  label: 'Contact Details',
+  fieldIds: [contactStep.id],
+})
+```
+
+## Use a condition in an experience
+
+A [condition](/reference/sdk/conditions) defines when an experience becomes active for the user.
+
+```ts
+import { createExperience, createStep } from '@picked/client/plugins/create-experience'
+
+const productPageFunnel = createExperience({
+  id: 'product-page-funnel',
+  name: 'Product Page Funnel',
+  condition: {
+    and: [
+      {
+        '==': [
+          {
+            var: 'location.pathname',
+          },
+          '/product/:id',
+        ],
+      },
+      {
+        var: 'actions.isSaleActive',
+      },
+    ],
+  },
+  targets: [{ selector: 'body', placement: 'after' }],
+})
+```
+
+A [condition](/reference/sdk/conditions) also controls the move from one step to the next.
+
+```ts
+import { createExperience, createStep } from '@picked/client/plugins/create-experience'
+```
+
+## Related
+
+- [Plugins](/reference/sdk/plugins)
+- [SDK experiences](/reference/sdk/experiences)
+- [Dynamic Experiences](/reference/sdk/plugins/dynamic-experiences) — the dashboard-driven
+  alternative.

package/docs/reference/sdk/plugins/dynamic-experiences.md

@@ -0,0 +1,74 @@
+---
+type: reference
+layout: docs
+---
+
+# Dynamic Experiences Plugin
+
+This plugin reads the configuration of your project from the Picked API at runtime. You can
+therefore control your experiences, feature flags, steps, fields, and conditions from
+the [dashboard](/reference/dashboard/experiences) alone.
+
+The plugin reads the configuration of your project and the CMS content of your
+experiences from one source. It does not mix them. Picked gives a configuration and its
+content the same version.
+
+## Options
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `mode` | `'bundle' \| 'api'` | see below | Where to read the configuration and the content from. |
+| `apiUrl` | `string` | `https://api.picked.app` | Your own API URL, for a self-hosted or local API. |
+| `projectConfig` | `ProjectConfig` | none | A configuration that you give. The plugin makes no request for it. |
+| `getContent` | `function` | none | A function that you give. The plugin calls it for each experience that uses CMS content. |
+
+### mode
+
+| Value | Source | Use it when |
+| --- | --- | --- |
+| `'bundle'` | The data that the [Vite plugin](/reference/tools/vite-plugin) puts in your build | You want no API request when the page loads. |
+| `'api'` | The Picked API, read when the client starts | You want a workspace publish to reach users without a new deployment. |
+
+:::code-group
+
+```ts [app.ts]
+import { createClient } from 'picked'
+import { dynamicExperiencesPlugin } from '@picked/client/plugins/dynamic-experiences'
+
+const client = createClient({
+  projectId: 'your-project-id',
+  plugins: [dynamicExperiencesPlugin({ mode: 'bundle' })],
+})
+
+client.start()
+```
+
+:::
+
+If you do not set `mode`, the plugin uses the build data when the Vite plugin gave it
+some. In every other case it uses the API.
+
+### projectConfig and getContent
+
+These two replace the source for you. Keep the configuration and the content at the same
+version when you use them. The plugin cannot make that check for you.
+
+## Preview mode
+
+After you [enter preview mode from the dashboard](/how-to/preview-a-workspace), the SDK
+receives a preview token and starts preview mode:
+
+- The plugin reads fresh options from the API with that token, for any value of `mode`.
+  It does not read the build-time configuration, a `projectConfig` that you give, or the
+  cached options.
+- A feature flag decision uses session storage. The decision resets when you close
+  the tab.
+
+A `getContent` function keeps its place in a preview session, and it receives the token.
+You therefore decide what a preview means for your own content.
+
+## Related
+
+- [About how Picked works](/explanation/how-picked-works) — how the plugin resolves your
+  options at startup.
+- [About feature flag allocation](/explanation/feature-flag-allocation)

package/docs/reference/sdk/plugins/fingerprintjs.md

@@ -0,0 +1,39 @@
+---
+type: reference
+layout: docs
+---
+
+# FingerprintJS
+
+`@picked/fingerprintjs` adds the FingerprintJS visitor ID to the Picked session.
+
+```ts
+import { createClient } from 'picked'
+import { fingerprintjsPlugin } from '@picked/fingerprintjs'
+
+const client = createClient({
+  projectId: 'your-project-id',
+  plugins: [fingerprintjsPlugin()],
+})
+```
+
+The plugin has no options.
+
+## Visitor ID
+
+The plugin reads `window.FingerprintJS`, which your own FingerprintJS script gives. The
+plugin does not load FingerprintJS.
+
+| Case | Result |
+| --- | --- |
+| `window.FingerprintJS` is there in 10 seconds | The plugin calls `load()` and `get()`. It sets the `fingerprintjs_visitor_id` session identifier to the `visitorId`. |
+| `window.FingerprintJS` is not there after 10 seconds | The plugin removes the `fingerprintjs_visitor_id` session identifier. |
+
+The SDK sends `fingerprintjs_visitor_id` in the `session` context of each analytics event.
+See [Analytics events](/reference/sdk/analytics-events).
+
+The plugin does nothing outside a browser.
+
+## Related
+
+- [Plugins](/reference/sdk/plugins)

package/docs/reference/sdk/plugins/hotjar.md

@@ -0,0 +1,60 @@
+---
+type: reference
+layout: docs
+---
+
+# Hotjar
+
+`@picked/hotjar` sends the events of the Picked client to Hotjar. Each event becomes a
+Hotjar event, and the session ID identifies the Hotjar user.
+
+```ts
+import { createClient } from 'picked'
+import { hotjarPlugin } from '@picked/hotjar'
+
+const client = createClient({
+  projectId: 'your-project-id',
+  plugins: [hotjarPlugin({ siteId: 1234567 })],
+})
+```
+
+## Options
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `siteId` | `number` | required | The ID of your Hotjar site. |
+| `snippetVersion` | `number` | `6` | The version of the Hotjar script. |
+| `trackedEvents` | `string[]` | See [Events](#events) | The client events that the plugin sends to Hotjar. |
+| `getUserAttributes` | `() => Record<string, string \| number \| boolean>` | none | Gives more attributes for the Hotjar user. |
+| `autoStartRecording` | `boolean` | `true` | Sends `recordingStartEvent` on the first `experience_initialize` event. |
+| `recordingStartEvent` | `string` | `'hotjar_start'` | The name of the Hotjar event that starts a recording. |
+
+## Events
+
+The default value of `trackedEvents` is:
+
+- `step_enter`
+- `step_complete`
+- `step_submit`
+- `field_validation_error`
+- `experience_complete`
+- `experience_initialize`
+- `session`
+
+The plugin starts Hotjar on the first tracked event. The name of each Hotjar event is the
+event type, the experience name, and the step name, joined by `>`. An example is
+`step_enter > Quiz > Question 1`. An event without an experience has only its type.
+
+The plugin keeps each event until Hotjar is ready, and then sends the events in order.
+
+## User attributes
+
+On the `session` event, the plugin calls `Hotjar.identify` with the session ID. The
+attributes are `projectId` and the return value of `getUserAttributes`.
+
+The plugin does nothing outside a browser.
+
+## Related
+
+- [Plugins](/reference/sdk/plugins)
+- [Analytics events](/reference/sdk/analytics-events)

package/docs/reference/sdk/plugins/index.md

@@ -0,0 +1,33 @@
+---
+type: reference
+layout: docs
+---
+
+# Plugins
+
+A plugin adds behaviour to the Picked client. Pass one to the `plugins` array of
+`createClient()`.
+
+| Plugin | Import | What it does |
+| --- | --- | --- |
+| [Dynamic Experiences](/reference/sdk/plugins/dynamic-experiences) | `@picked/client/plugins/dynamic-experiences` | Reads the published configuration of your project at runtime and registers every experience, step, field, condition, and feature flag. |
+| [Create Experience](/reference/sdk/plugins/create-experience) | `@picked/client/plugins/create-experience` | Registers an experience, a step, and a field that you define in code. |
+| [Window Object](/reference/sdk/plugins/window-object) | `@picked/client/plugins/window-object` | Puts the client on `window.Picked`, which helps when you debug. |
+| Single Page App | `@picked/client/plugins/single-page-app` | Starts the client again on a history event. |
+| [React framework](/reference/sdk/react) | `@picked/react/plugins/framework` | Lets the client render a React component. |
+| [Svelte framework](/reference/sdk/svelte) | `@picked/svelte/plugins/framework` | Lets the client render a Svelte component. |
+| [Devtools](/reference/sdk/svelte#devtools-plugin) | `@picked/svelte/plugins/devtools` | Connects the client to the Chrome extension. |
+| [Hotjar](/reference/sdk/plugins/hotjar) | `@picked/hotjar` | Sends the events of the client to Hotjar. |
+| [FingerprintJS](/reference/sdk/plugins/fingerprintjs) | `@picked/fingerprintjs` | Adds the FingerprintJS visitor ID to the session. |
+| [Sentry](/reference/sdk/plugins/sentry) | `@picked/sentry` | Sends the errors of the client to Sentry, and adds Picked tags. |
+| [Shopify](/reference/sdk/plugins/shopify) | `@picked/shopify/plugins/shopify` | Adds Shopify predicates, and writes Picked data to the cart. |
+
+Most applications need a framework plugin and **one** of Dynamic Experiences or Create
+Experience. Dynamic Experiences puts your options in the dashboard; Create Experience
+puts them in code.
+
+## Related
+
+- [How to install the SDK](/how-to/install-the-sdk) — where the plugins go.
+- [SDK installation](/reference/sdk) — every client option.
+- [How to debug with the Chrome extension](/how-to/debug-with-the-chrome-extension)

package/docs/reference/sdk/plugins/sentry.md

@@ -0,0 +1,51 @@
+---
+type: reference
+layout: docs
+---
+
+# Sentry
+
+`@picked/sentry` sends the errors of the Picked client to Sentry, and adds Picked tags to
+the Sentry scope.
+
+```ts
+import * as Sentry from '@sentry/browser'
+import { createClient } from 'picked'
+import { sentryPlugin } from '@picked/sentry'
+
+Sentry.init({ dsn: 'https://examplePublicKey@o0.ingest.sentry.io/0' })
+
+const client = createClient({
+  projectId: 'your-project-id',
+  plugins: [sentryPlugin()],
+})
+```
+
+The plugin has no options. It uses the global Sentry scope of your application.
+
+## Requirements
+
+| Peer dependency | Version |
+| --- | --- |
+| `@sentry/browser` | `^10` |
+| `@picked/client` | The version of your Picked SDK |
+
+All the Sentry packages in your application must have the same version, for example `10.x`. A
+different version makes a different Sentry scope, and the plugin then sends nothing.
+
+## Events
+
+| Client event | Sentry result |
+| --- | --- |
+| `exception` with `level: 'info'` | `captureMessage`, with the tag `picked: true`. |
+| `exception` with a different `level` | `captureException`, with the tag `picked: true`. |
+| `session` | The tag `picked.id`, with the session ID as its value. |
+| `feature_decide` | The tag `picked.feature.<feature ID>`, with the bucket of the feature as its value. |
+| `user_decide` | The tag `picked.is_user`, with the decision as its value. |
+
+The plugin does nothing outside a browser.
+
+## Related
+
+- [Plugins](/reference/sdk/plugins)
+- [About feature flag allocation](/explanation/feature-flag-allocation)