Trigger Flows Using the JavaScript API

Before You Start

A Flow must use the On launch request trigger before you can start it through the JavaScript API or a URL parameter.

In the Flow editor:

1. Open the Flow.
2. Select the Start step.
3. Set Start the flow to On launch request.
4. Copy the Flow’s Public ID from the Enter-step settings.

Start a Flow with JavaScript

Product Fruits provides the global $pfai command queue. You can use it before or after the Product Fruits script finishes loading.

Replace YOUR_FLOW_PUBLIC_ID with the Public ID from the Flow’s Enter step:

window.$pfai.push([
  'run',
  'flow',
  'YOUR_FLOW_PUBLIC_ID'
]);

The user must meet the Flow’s normal eligibility and targeting conditions.

Start a Flow Regardless of Eligibility

Add the force option when the Flow should start even if the user would not normally be eligible:

window.$pfai.push([
  'run',
  'flow',
  'YOUR_FLOW_PUBLIC_ID',
  { force: true }
]);

Use force: true carefully. It can restart the Flow for users who have already completed or seen it, depending on how your integration invokes the command.

For example, this can be useful when a Flow acts as an on-demand form that should open every time a user performs a specific action.

Start Multiple Flows

To request multiple Flows at once, pass their Public IDs to flow-batch:

window.$pfai.push([
  'run',
  'flow-batch',
  ['FLOW_PUBLIC_ID_1', 'FLOW_PUBLIC_ID_2']
]);

Product Fruits still controls when each Flow can appear and coordinates them with other content waiting to be displayed.

Start a Flow from a URL

You can also start a manually triggered Flow by adding pf_start_flow to a page URL:

https://yourapp.com/dashboard?pf_start_flow=YOUR_FLOW_PUBLIC_ID

When the Product Fruits widget loads:

• The Flow is started with forced enrollment.
• Normal eligibility and targeting checks are bypassed.
• Product Fruits removes pf_start_flow from the address bar.
• The parameter also works with URL changes in single-page applications.

If the Public ID does not match a Flow available in the current configuration, Product Fruits writes a warning to the browser console.

Anyone with a URL containing this parameter can attempt to start the Flow. Avoid publishing such links unless forced enrollment is intentional.

Detect When a Flow Finishes

Listen for the pfFlowFinished browser event:

window.addEventListener('pfFlowFinished', (event) => {
  console.log('Flow:', event.detail.flowId);
  console.log('Enrollment:', event.detail.enrollmentId);
});

The event details include:

You can use this event to refresh your application, record an analytics event, or run another action after completion.

Listen for Flow State Changes

Use pf_flow_state_changed when your integration needs to react to any change in Flow state:

window.addEventListener('pf_flow_state_changed', () => {
  // Re-check the relevant Flow states here.
});

This event indicates that Flow state has changed. It does not specify which state changed, so your code should re-check the state it depends on.

Troubleshoot Flows with the Debug Overlay

Product Fruits includes an on-page debugging overlay for developers and administrators.

Open it through the command queue:

window.$pfai.push([
  'config',
  'toggle-debugger',
  { force: true }
]);

You can also enable it directly:

window.productFruits.flows.debug(true);

The overlay contains three sections:

• Overview — the current runtime and state snapshot.
• Flows — loaded Flows and their current states.
• Queue — content waiting to be displayed.

The panel can be dragged around the page. If it is collapsed, double-click its pill to expand it.

To disable the direct debug mode:

window.productFruits.flows.debug(false);

The debug overlay is intended for troubleshooting. Do not enable it permanently for end users.

View Enrollment Logs in the Flow Editor

The Flow editor also provides debugging information for an individual Flow:

1. Open the Flow’s Enter step.
2. Select Debug logs using the bug icon.
3. Review the Enrolled Users view.

This editor-side tool is separate from the on-page debug overlay and the JavaScript API.

Quick Reference

// Start a manually triggered Flow
window.$pfai.push([
  'run',
  'flow',
  'YOUR_FLOW_PUBLIC_ID'
]);

// Start a Flow while bypassing eligibility and targeting
window.$pfai.push([
  'run',
  'flow',
  'YOUR_FLOW_PUBLIC_ID',
  { force: true }
]);

// Start multiple Flows
window.$pfai.push([
  'run',
  'flow-batch',
  ['FLOW_PUBLIC_ID_1', 'FLOW_PUBLIC_ID_2']
]);

// Listen for Flow completion
window.addEventListener('pfFlowFinished', (event) => {
  console.log(event.detail.flowId);
  console.log(event.detail.enrollmentId);
});

// Listen for any Flow state change
window.addEventListener('pf_flow_state_changed', () => {
  // Re-check Flow states
});

// Open the debug overlay
window.$pfai.push([
  'config',
  'toggle-debugger',
  { force: true }
]);

// Alternative debug API
window.productFruits.flows.debug(true);