feat(*): navigate hooks + spaNavigationHandler for JS SDKs

packages/sdk-angular/docs/classes/Screeb.md

@@ -360,7 +360,7 @@ ___
 
 ### init
 
-▸ **init**(`websiteId`, `userId?`, `userProperties?`, `hooks?`, `language?`): `Promise`\<`unknown`\>
+▸ **init**(`websiteId`, `userId?`, `userProperties?`, `hooks?`, `language?`, `spaNavigationHandler?`): `Promise`\<`unknown`\>
 
 Initializes Screeb tag.
 
@@ -373,6 +373,7 @@ Initializes Screeb tag.
 | `userProperties?` | `PropertyRecord` | The properties of your user. ```text Requirements: - Property names must be limited to 128 characters - No more than 1000 attributes - Supported types for values: string, number, boolean and Date ``` |
 | `hooks?` | `HooksInit` | - |
 | `language?` | `string` | Force a specific language for the tag. eg: 'en'. default: browser language. |
+| `spaNavigationHandler?` | `SpaNavigationHandler` | - |
 
 #### Returns
 

packages/sdk-angular/docs/classes/ScreebConfig.md

@@ -16,6 +16,7 @@ Configuration of Screeb module
 - [hooks](ScreebConfig.md#hooks)
 - [options](ScreebConfig.md#options)
 - [shouldLoad](ScreebConfig.md#shouldload)
+- [spaNavigationHandler](ScreebConfig.md#spanavigationhandler)
 - [userId](ScreebConfig.md#userid)
 - [userProperties](ScreebConfig.md#userproperties)
 - [websiteId](ScreebConfig.md#websiteid)
@@ -77,6 +78,14 @@ if `true`, 'load' does not need to be called manually. Can be used for multistag
 
 ___
 
+### spaNavigationHandler
+
+• `Optional` **spaNavigationHandler**: `SpaNavigationHandler`
+
+Optional handler for the `in-page-spa` "Navigate to URL" target (custom SPA routers).
+
+___
+
 ### userId
 
 • `Optional` **userId**: `string`

packages/sdk-angular/projects/sdk-angular/src/lib/screeb-config.ts

@@ -1,5 +1,10 @@
 import { Injectable } from "@angular/core";
-import { HooksInit, PropertyRecord, ScreebOptions } from "@screeb/sdk-browser";
+import {
+  HooksInit,
+  PropertyRecord,
+  ScreebOptions,
+  SpaNavigationHandler,
+} from "@screeb/sdk-browser";
 
 /** Configuration of Screeb module */
 @Injectable({ providedIn: "root" })
@@ -12,6 +17,8 @@ export class ScreebConfig {
   userProperties?: PropertyRecord;
   /** Hooks to define callback for various event */
   hooks?: HooksInit;
+  /** Optional handler for the `in-page-spa` "Navigate to URL" target (custom SPA routers). */
+  spaNavigationHandler?: SpaNavigationHandler;
   /**
    * Indicates if Screeb should be automatically loaded.
    * This will ping to the Screeb servers.

packages/sdk-angular/projects/sdk-angular/src/lib/screeb.module.ts

@@ -50,7 +50,9 @@ export class ScreebModule {
         config.websiteId,
         config.userId,
         config.userProperties,
-        config.hooks
+        config.hooks,
+        undefined,
+        config.spaNavigationHandler
       );
     }
   }

packages/sdk-angular/projects/sdk-angular/src/lib/screeb.ts

@@ -489,7 +489,8 @@ export class Screeb {
     userId?: string,
     userProperties?: _Screeb.PropertyRecord,
     hooks?: _Screeb.HooksInit,
-    language?: string
+    language?: string,
+    spaNavigationHandler?: _Screeb.SpaNavigationHandler
   ) {
     await this.ensureScreeb("init", true);
 
@@ -500,7 +501,8 @@ export class Screeb {
       userId,
       userProperties,
       hooks,
-      language
+      language,
+      spaNavigationHandler
     );
   }
 

packages/sdk-browser/docs/README.md

@@ -11,6 +11,8 @@
 - [HookCommonProperties](README.md#hookcommonproperties)
 - [HookCommonPropertiesMessage](README.md#hookcommonpropertiesmessage)
 - [HookCommonPropertiesSurvey](README.md#hookcommonpropertiessurvey)
+- [HookOnButtonNavigateCompleted](README.md#hookonbuttonnavigatecompleted)
+- [HookOnButtonNavigateStarted](README.md#hookonbuttonnavigatestarted)
 - [HookOnMessageCompleted](README.md#hookonmessagecompleted)
 - [HookOnMessageDisplayAllowed](README.md#hookonmessagedisplayallowed)
 - [HookOnMessageHidden](README.md#hookonmessagehidden)
@@ -38,6 +40,7 @@
 - [ScreebIdentityGetReturn](README.md#screebidentitygetreturn)
 - [ScreebObject](README.md#screebobject)
 - [ScreebOptions](README.md#screeboptions)
+- [SpaNavigationHandler](README.md#spanavigationhandler)
 - [Survey](README.md#survey)
 - [SurveyFormat](README.md#surveyformat)
 - [SurveyPosition](README.md#surveyposition)
@@ -112,6 +115,46 @@ ___
 
 ___
 
+### HookOnButtonNavigateCompleted
+
+Ƭ **HookOnButtonNavigateCompleted**: (`data`: [`HookCommonPropertiesSurvey`](README.md#hookcommonpropertiessurvey) & \{ `button`: \{ `url`: `string` ; `url_target?`: `string`  } ; `response`: \{ `id`: `string`  }  }) => `void`
+
+#### Type declaration
+
+▸ (`data`): `void`
+
+##### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `data` | [`HookCommonPropertiesSurvey`](README.md#hookcommonpropertiessurvey) & \{ `button`: \{ `url`: `string` ; `url_target?`: `string`  } ; `response`: \{ `id`: `string`  }  } |
+
+##### Returns
+
+`void`
+
+___
+
+### HookOnButtonNavigateStarted
+
+Ƭ **HookOnButtonNavigateStarted**: (`data`: [`HookCommonPropertiesSurvey`](README.md#hookcommonpropertiessurvey) & \{ `button`: \{ `url`: `string` ; `url_target?`: `string`  } ; `response`: \{ `id`: `string`  }  }) => `void`
+
+#### Type declaration
+
+▸ (`data`): `void`
+
+##### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `data` | [`HookCommonPropertiesSurvey`](README.md#hookcommonpropertiessurvey) & \{ `button`: \{ `url`: `string` ; `url_target?`: `string`  } ; `response`: \{ `id`: `string`  }  } |
+
+##### Returns
+
+`void`
+
+___
+
 ### HookOnMessageCompleted
 
 Ƭ **HookOnMessageCompleted**: (`data`: [`HookCommonPropertiesMessage`](README.md#hookcommonpropertiesmessage) & \{ `response`: \{ `id`: `string` ; `items`: [`ResponseItem`](README.md#responseitem)[]  }  }) => `void`
@@ -372,6 +415,8 @@ This is the Screeb tag hooks object available on `message.start` command.
 
 | Name | Type | Description |
 | :------ | :------ | :------ |
+| `onButtonNavigateCompleted?` | [`HookOnButtonNavigateCompleted`](README.md#hookonbuttonnavigatecompleted) | This hook is triggered after a message/tour button "Navigate to URL" action ran (only fires when the SDK survives the navigation, e.g. `new-tab` or `in-page-spa`). |
+| `onButtonNavigateStarted?` | [`HookOnButtonNavigateStarted`](README.md#hookonbuttonnavigatestarted) | This hook is triggered before a message/tour button "Navigate to URL" action runs. |
 | `onMessageCompleted?` | [`HookOnMessageCompleted`](README.md#hookonmessagecompleted) | This hook is triggered when a message is completed |
 | `onMessageHidden?` | [`HookOnMessageHidden`](README.md#hookonmessagehidden) | This hook is triggered when a message is hidden |
 | `onMessageShowed?` | [`HookOnMessageShowed`](README.md#hookonmessageshowed) | This hook is triggered when a message is displayed on screen (also triggered when page is reloaded) |
@@ -390,6 +435,8 @@ This is the Screeb tag hooks object available on `survey.start` command.
 
 | Name | Type | Description |
 | :------ | :------ | :------ |
+| `onButtonNavigateCompleted?` | [`HookOnButtonNavigateCompleted`](README.md#hookonbuttonnavigatecompleted) | This hook is triggered after a message/tour button "Navigate to URL" action ran (only fires when the SDK survives the navigation, e.g. `new-tab` or `in-page-spa`). |
+| `onButtonNavigateStarted?` | [`HookOnButtonNavigateStarted`](README.md#hookonbuttonnavigatestarted) | This hook is triggered before a message/tour button "Navigate to URL" action runs. |
 | `onQuestionReplied?` | [`HookOnQuestionReplied`](README.md#hookonquestionreplied) | This hook is triggered when a question is answered |
 | `onSurveyCompleted?` | [`HookOnSurveyCompleted`](README.md#hookonsurveycompleted) | This hook is triggered when a survey is completed |
 | `onSurveyHidden?` | [`HookOnSurveyHidden`](README.md#hookonsurveyhidden) | This hook is triggered when a survey is hidden |
@@ -571,6 +618,33 @@ This is the Screeb tag options object.
 
 ___
 
+### SpaNavigationHandler
+
+Ƭ **SpaNavigationHandler**: (`url`: `string`) => `void` \| `Promise`\<`void`\>
+
+Host-provided navigation handler for the `in-page-spa` "Navigate to URL"
+target. It runs in your page (where your SPA router lives) instead of the tag
+doing a `history.pushState` + `popstate` dispatch itself. Provide this when
+your router does not resync on `popstate` (most React Router / Vue Router /
+Angular Router setups do, so this is only needed for custom routers). May be
+async so `onButtonNavigateCompleted` can await the route change.
+
+#### Type declaration
+
+▸ (`url`): `void` \| `Promise`\<`void`\>
+
+##### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `url` | `string` |
+
+##### Returns
+
+`void` \| `Promise`\<`void`\>
+
+___
+
 ### Survey
 
 Ƭ **Survey**: `Object`
@@ -913,7 +987,7 @@ ___
 
 ### init
 
-▸ **init**(`websiteId`, `userId?`, `userProperties?`, `hooks?`, `language?`): `void` \| `Promise`\<`unknown`\>
+▸ **init**(`websiteId`, `userId?`, `userProperties?`, `hooks?`, `language?`, `spaNavigationHandler?`): `void` \| `Promise`\<`unknown`\>
 
 Initializes Screeb tag.
 
@@ -926,6 +1000,7 @@ Initializes Screeb tag.
 | `userProperties?` | [`PropertyRecord`](README.md#propertyrecord) | The properties of your user. ```text Requirements: - Property names must be limited to 128 characters - No more than 1000 attributes - Supported types for values: string, number, boolean and Date ``` |
 | `hooks?` | [`HooksInit`](README.md#hooksinit) | Hooks to be called when SDK is ready or a survey is showed, started, completed, hidden or when a question is replied. |
 | `language?` | `string` | Force a specific language for the tag. eg: 'en'. default: browser language. |
+| `spaNavigationHandler?` | [`SpaNavigationHandler`](README.md#spanavigationhandler) | Optional handler for the `in-page-spa` "Navigate to URL" target. Runs in your page so your SPA router can navigate without a full reload. Only needed for custom routers that don't resync on `popstate` (React Router / Vue Router / Angular Router work out of the box). May be async so `onButtonNavigateCompleted` awaits it. |
 
 #### Returns
 
@@ -949,6 +1024,8 @@ Screeb.init(
   {
     version: "1.0.0",
     onReady: (payload) =>  console.log("Screeb SDK is ready!", payload),
+    onButtonNavigateStarted: (payload) => console.log("Button navigate started", payload),
+    onButtonNavigateCompleted: (payload) => console.log("Button navigate completed", payload),
   },
   "en"
 );

packages/sdk-browser/src/hooks.types.ts

@@ -183,6 +183,32 @@ export type HookOnQuestionReplied = (
   },
 ) => void;
 
+export type HookOnButtonNavigateStarted = (
+  // eslint-disable-next-line no-unused-vars
+  data: HookCommonPropertiesSurvey & {
+    response: {
+      id: string;
+    };
+    button: {
+      url: string;
+      url_target?: string;
+    };
+  },
+) => void;
+
+export type HookOnButtonNavigateCompleted = (
+  // eslint-disable-next-line no-unused-vars
+  data: HookCommonPropertiesSurvey & {
+    response: {
+      id: string;
+    };
+    button: {
+      url: string;
+      url_target?: string;
+    };
+  },
+) => void;
+
 /** This is the Screeb tag hooks object available on `survey.start` command. */
 export type HooksSurveyStart = {
   /** This hook is triggered when a survey is displayed on screen (also triggered when page is reloaded) */
@@ -196,6 +222,11 @@ export type HooksSurveyStart = {
 
   /** This hook is triggered when a question is answered */
   onQuestionReplied?: HookOnQuestionReplied;
+
+  /** This hook is triggered before a message/tour button "Navigate to URL" action runs. */
+  onButtonNavigateStarted?: HookOnButtonNavigateStarted;
+  /** This hook is triggered after a message/tour button "Navigate to URL" action ran (only fires when the SDK survives the navigation, e.g. `new-tab` or `in-page-spa`). */
+  onButtonNavigateCompleted?: HookOnButtonNavigateCompleted;
 };
 
 /** This is the Screeb tag hooks object available on `message.start` command. */
@@ -211,6 +242,11 @@ export type HooksMessageStart = {
 
   /** This hook is triggered when a question is answered */
   onQuestionReplied?: HookOnQuestionReplied;
+
+  /** This hook is triggered before a message/tour button "Navigate to URL" action runs. */
+  onButtonNavigateStarted?: HookOnButtonNavigateStarted;
+  /** This hook is triggered after a message/tour button "Navigate to URL" action ran (only fires when the SDK survives the navigation, e.g. `new-tab` or `in-page-spa`). */
+  onButtonNavigateCompleted?: HookOnButtonNavigateCompleted;
 };
 
 /** This is the Screeb tag hooks object available on `init` command. */

packages/sdk-browser/src/index.ts

@@ -6,6 +6,7 @@ import {
   ScreebIdentityGetReturn,
   ScreebObject,
   ScreebOptions,
+  SpaNavigationHandler,
 } from "./types";
 
 export * from "./types";
@@ -108,6 +109,11 @@ export const load = (options: ScreebOptions = {}) =>
  *
  * @param language Force a specific language for the tag. eg: 'en'. default: browser language.
  *
+ * @param spaNavigationHandler Optional handler for the `in-page-spa` "Navigate to URL"
+ * target. Runs in your page so your SPA router can navigate without a full reload. Only
+ * needed for custom routers that don't resync on `popstate` (React Router / Vue Router /
+ * Angular Router work out of the box). May be async so `onButtonNavigateCompleted` awaits it.
+ *
  * @example
  * ```ts
  * import * as Screeb from "@screeb/sdk-browser";
@@ -125,6 +131,8 @@ export const load = (options: ScreebOptions = {}) =>
  *   {
  *     version: "1.0.0",
  *     onReady: (payload) =>  console.log("Screeb SDK is ready!", payload),
+ *     onButtonNavigateStarted: (payload) => console.log("Button navigate started", payload),
+ *     onButtonNavigateCompleted: (payload) => console.log("Button navigate completed", payload),
  *   },
  *   "en"
  * );
@@ -136,12 +144,14 @@ export const init = (
   userProperties?: PropertyRecord,
   hooks?: HooksInit,
   language?: string,
+  spaNavigationHandler?: SpaNavigationHandler,
 ) => {
   let identityObject:
     | {
         hooks?: HooksInit;
         identity?: { id?: string; properties?: PropertyRecord };
         language?: string;
+        spaNavigationHandler?: SpaNavigationHandler;
       }
     | undefined;
 
@@ -159,6 +169,10 @@ export const init = (
     identityObject = { ...identityObject, language };
   }
 
+  if (spaNavigationHandler) {
+    identityObject = { ...identityObject, spaNavigationHandler };
+  }
+
   return callScreebCommand("init", websiteId, identityObject);
 };
 

packages/sdk-browser/src/types.ts

@@ -55,6 +55,17 @@ export type ScreebOptions = {
   platform?: string;
 };
 
+/**
+ * Host-provided navigation handler for the `in-page-spa` "Navigate to URL"
+ * target. It runs in your page (where your SPA router lives) instead of the tag
+ * doing a `history.pushState` + `popstate` dispatch itself. Provide this when
+ * your router does not resync on `popstate` (most React Router / Vue Router /
+ * Angular Router setups do, so this is only needed for custom routers). May be
+ * async so `onButtonNavigateCompleted` can await the route change.
+ */
+// eslint-disable-next-line no-unused-vars
+export type SpaNavigationHandler = (url: string) => void | Promise<void>;
+
 // eslint-disable-next-line no-unused-vars
 export type ScreebFunction = (..._: unknown[]) => void | Promise<unknown>;
 

packages/sdk-react/docs/README.md

@@ -367,7 +367,7 @@ ___
 
 ### InitFunction
 
-Ƭ **InitFunction**: (`websiteId`: `string`, `userId?`: `string`, `userProperties?`: `PropertyRecord`, `hooks?`: `HooksInit`, `language?`: `string`) => `Promise`\<`void`\>
+Ƭ **InitFunction**: (`websiteId`: `string`, `userId?`: `string`, `userProperties?`: `PropertyRecord`, `hooks?`: `HooksInit`, `language?`: `string`, `spaNavigationHandler?`: `SpaNavigationHandler`) => `Promise`\<`void`\>
 
 Initializes Screeb tag.
 
@@ -392,7 +392,7 @@ init(
 
 #### Type declaration
 
-▸ (`websiteId`, `userId?`, `userProperties?`, `hooks?`, `language?`): `Promise`\<`void`\>
+▸ (`websiteId`, `userId?`, `userProperties?`, `hooks?`, `language?`, `spaNavigationHandler?`): `Promise`\<`void`\>
 
 ##### Parameters
 
@@ -403,6 +403,7 @@ init(
 | `userProperties?` | `PropertyRecord` | The properties of your user. ```text Requirements: - Property names must be limited to 128 characters - No more than 1000 attributes - Supported types for values: string, number, boolean and Date ``` |
 | `hooks?` | `HooksInit` | - |
 | `language?` | `string` | Force a specific language for the tag. eg: 'en'. default: browser language. |
+| `spaNavigationHandler?` | `SpaNavigationHandler` | - |
 
 ##### Returns
 
@@ -548,6 +549,7 @@ Properties of Screeb provider
 | :------ | :------ | :------ |
 | `hooks?` | `HooksInit` | Hooks to define callback for various event |
 | `language?` | `string` | The language you want to force |
+| `spaNavigationHandler?` | `SpaNavigationHandler` | Optional handler for the `in-page-spa` "Navigate to URL" target (custom SPA routers). |
 | `userId?` | `string` | The unique identifier of your user. |
 | `userProperties?` | `PropertyRecord` | The properties of your user. |
 | `websiteId` | `string` | Your website/channel id. |