Custom Interactive Flow Development

To implement a custom flow, knowledge of the following components is required:

• OnliveFlowAPI: API responsible for managing user interactions. This API receives the actions performed by the user and returns the definition of an interaction stage.
• FlowClient: JavaScript class that implements the operations to be performed on a flow. This class is found in the @onlive.site/flow-client package.
• WebApp: The web application that implements an interactive flow using FlowClient.

The following diagram shows an overview of the interaction between the components:

FlowClient

The FlowClient class facilitates communication with the OnliveFlowAPI to manage the stages of an interactive flow. It provides methods to obtain, navigate, and interact with the different stages of a flow.

Key Responsibilities:

• Obtain the first stage of a flow.
• Retrieve details of a specific stage.
• Trigger actions to move to the next stage.

Installation

ES6 Module

Using module imports, you need to create the .npmrc file at the root of the project with the following content:

@onlive.site:registry=https://gitlab.com/api/v4/projects/66230274/packages/npm/

Then, you can install the package with the following command:

npm install @onlive.site/flow-client

import { FlowClient } from "@onlive.site/flow-client";

const client = new FlowClient({
  baseUrl: "https://example.com/api/v1",
  flowId: "<flowId>",
  organizationId: "<organizationId>",
  lang: "es",
  tracking: {
    enabled: true
  }
});

UMD (Universal Module Definition)

<script src="https://cdn.onlive.site/@onlive.site/flow-client@latest/index.iife.js"></script>

<script>
  const { FlowClient } = window.OnliveFlowClient;

  const client = new FlowClient({
    baseUrl: "https://example.com/api/v1",
    flowId: "<flowId>",
    organizationId: "<organizationId>",
    lang: "es",
    tracking: {
      enabled: true
    }
  });
</script>

Usage

Constructor

Signature:

constructor(_options: ClientOptions)

• Initializes a new instance of FlowClient.
• Parameters:
  • _options (ClientOptions): Configuration object for the client, validated according to ClientOptionsSchema.

---

Methods

1. firstStep

Description:

Obtains the definition of the first stage of a flow.

Signature:

async firstStep(options: GetStepOptions): Promise<FlowContext>

• Parameters:

  • options (GetStepOptions): State or fields used to initialize the stage.

• Returns:

  • FlowContext: The context of the first stage defined using the FlowContextSchema.

Example:

const firstStep = await client.firstStep({ state: {} });
console.log(firstStep);

---

2. getStep

Description:

Obtains the details of a specific stage of the flow.

Signature:

async getStep(stepId: string, options: GetStepOptions): Promise<FlowContext>

• Parameters:

  • stepId (string): ID of the stage to retrieve.
  • options (GetStepOptions): State or additional fields.

• Returns:

  • FlowContext: The context of the requested stage defined using the FlowContextSchema.

Example:

const step = await client.getStep("step123", { state: {} });
console.log(step);

---

3. nextStep

Description:

Requests the definition of the next stage. It is necessary to specify in the nextStep request that the fields field with the values of the fields presented in the stage is sent within the options parameter.

Signature:

async nextStep(trigger: GetStepTrigger, options: GetStepOptions): Promise<FlowContext>

• Parameters:

  • trigger (GetStepTrigger): Contains currentStepId and actionId to specify the action.
  • options (GetStepOptions): State or additional fields.

• Returns:

  • FlowContext: The context of the next stage defined using the FlowContextSchema. The fields sent in the request of this method are found in the state field of the returned object, within a field with the identifier equal to the name of the stage.

Example:

const nextStep = await client.nextStep(
  { currentStepId: "step123", actionId: "action456" },
  { state: {} }
);
console.log(nextStep);

---

Properties

tracking

Description:

Configures the tracking options for the flow.

Signature:

tracking: TrackingService

• Methods:

  • send (EventName, EventData): Sends tracking events to the tracking service.
    • Parameters:
      • EventName (string): Name of the event to be sent.
      • EventData (object): Data associated with the event.
  • setData (data: EventData): Sets the data to be sent with the tracking events.
    • Parameters:
      • data (EventData): Data to be sent with the tracking events.
  • onEvent (callback: Function): Sets a callback function to be executed when an event is triggered.
    • Parameters:
      • callback (Function): Callback function to be executed when an event is triggered.

Example Send:

client.tracking.send("impression", {
  "impression_type": "widget"
});

Example Set Data:

client.tracking.setData({
  "extra": {
    "extra_data": "value"
  }
});

Example On Event:

client.tracking.onEvent((event) => {
  console.log("Event triggered:", event.event);
  console.log("Event data:", event.data);
});

---

The following diagram shows the sequence of messages between these components:

Interactive Example

You can test the interactive flow using the following link: https://client.onlive.site/demo/onlive-flow-interactive-demo/index.html