For the complete documentation index, see llms.txt. This page is also available as Markdown.

Handling Selection

Read and control the customer's selection.

Use on(event, handler) to receive events from the SDK.

cgElement.on('change', (detail) => { /* ... */ });

on() keeps one handler for each event. A new call for the same event replaces the earlier handler. This prevents duplicate handlers when your framework renders again.

ready

Fires one time, when the panel first shows. It has no payload.

change

Fires when the selection changes. This includes a customer action and a call to selection.set().

Field
Type
Meaning

selectedOption

string

The stable ID of the option that changed, for example opt_in_1 or opt_out.

selectedProductIDs

string[]

The quote IDs that are now selected. Empty when the customer declines.

declined

boolean (optional)

true when the customer chose "no cover". Never true with quote IDs.

When an offer allows more than one option at once, selectedOption is the option that the customer just toggled. selectedProductIDs holds every selected quote ID.

error

Fires when the SDK cannot render the panel. The SDK hides the panel.

Field
Type
Meaning

code

string

The reason. See Errors and Troubleshooting.

message

string

A description for developers.

Show your normal checkout without the offer when this event fires.

Selection methods

The selection object on the instance controls the selection from your code.

Method
Effect

selection.set(optionId)

Chooses an option. Use an option ID such as opt_in_1 or opt_out.

selection.get()

Returns the last selected option ID, or null.

selection.getAll()

Returns every selected option ID, in the order selected. Returns [] if none.

selection.reset()

Clears the selection and the required prompt.

selection.required()

Shows the "you must choose" prompt.

Require a choice

Some offers need an explicit answer. Call selection.required() when the customer submits your form with no selection.

Offers with several options

The product_rules field of the offer response sets how many options the customer can choose. If an offer allows one option, the SDK shows radio controls. If it allows more than one, the SDK shows checkboxes.

Some choices show or hide other options. For example, a decline can reveal a second group. The SDK handles these reactions. Your code only reads the change event.

Example

Last updated

Was this helpful?