JavaScript API and events

The SubcontextNurture methods, switching client without a reload, and the events and callbacks your page can listen for.

JavaScript API#

The script creates window.SubcontextNurture as soon as it loads.

Method Returns What it does
init(options?) true or false Starts the widget using the tag's settings plus options. On a running widget, restarts it with the new options (unless they are the same as before, see Starting it from JavaScript). Returns false, with a console warning, if there is no key or firm id; a running widget is then left as it was.
enable() nothing Starts a widget that was loaded with enabled: false, or shows one hidden by disable().
disable() nothing Closes the form and hides the widget.
destroy() nothing Removes the widget and forgets its settings. Call init() to start it again.
open() nothing Opens the form, for example from a button in your own toolbar.
close() nothing Closes the form and stops any drafting or sending that is in progress.
setConsumer(consumer, advisor?, extras?) nothing Switches to another client without reloading the page. See below.
version text The widget's version, such as 0.1.0. It is also printed in the console when the widget starts.

Switching client without a reload: setConsumer#

In a single-page portal, call setConsumer when the adviser opens another client record:

js 
SubcontextNurture.setConsumer(
  { firstName: 'Tom', lastName: 'Okafor', email: 'tom@example.com', phone: '07700 900123', externalId: 'CLIENT-456' },
  { name: 'Sam Patel', externalId: 'ADVISER-7', email: 'sam@example.com' },   // optional
  { draftNote: 'Wants to review his cover in March.', subcontext: { quotes: [] }, identityToken: 'NEW_PASS' } // optional
)
  • Anything in progress for the previous client is dropped and the form closes. In docked mode the form moves straight on to the new client.
  • Always pass the whole client. Any field you leave out is cleared, so one client's email or mobile is never used for the next client.
  • advisor is optional. If you pass it, it replaces the adviser in the same way. If you leave it out, the adviser stays the same. A different adviser id makes the widget check the terms again, because terms are per adviser.
  • extras is optional. Each key you include replaces that value (null or '' clears it). Keys you leave out stay as they were. If the adviser changes, include a new identityToken, because each pass names one adviser.
  • The firm and widget key can't be changed this way. Call destroy() and then init() instead.
  • It does nothing until the widget has started.
  • Merge-field tokens are handled the same way as everywhere else.

Events#

The widget fires an event on window and calls the matching function you passed to init(). Both get the same detail.

Event init() function When detail
subcontext:nurture:ready onReady The widget has been drawn (each start, and enable() after enabled: false). { version, firmId, mode }
subcontext:nurture:drafted onDrafted New drafts are ready for the adviser to check, after Generate or "Try another draft". { consumerExternalId, requests }. requests is a list of { channel, requestId, drafted }; drafted: false means that channel's draft failed.
subcontext:nurture:sent onSent The adviser sent the messages. { consumerExternalId, requests, delivered, queued, failedChannels }
subcontext:nurture:refused onRefused The widget is showing "Not enabled yet". { code, message, status }, with one of the codes in Troubleshooting. Or { code: 'no_channels', message } when the firm has no channel it can send on.
subcontext:nurture:error onError The widget has stopped on its error screen. { code, message }. code is a reason such as identity_expired, network or timeout, or send_failed when nothing could be delivered, or error.

For example, to note the follow-up on the client's record in your portal:

js 
window.addEventListener('subcontext:nurture:sent', (event) => {
  const { consumerExternalId, requests, delivered } = event.detail
  portal.recordActivity(consumerExternalId, `Nurture started (${delivered} sent)`, requests)
})

SubcontextNurture.init({
  integrationKey: 'YOUR_WIDGET_KEY',
  firmId: 'YOUR_FIRM_ID',
  onRefused: ({ code, message }) => portal.reportProblem('nurture', code, message)
})
  • consumerExternalId is the client id you passed (the latest one, if you used setConsumer).
  • Problems the adviser can fix in the form, such as a message under a field or a failed draft tab, are not events.
  • If one of your functions throws an error, it is logged and the widget carries on.
  • ready fires as the widget starts. Add your listener before the script tag, or use onReady.
  • The widget doesn't read anything else from your page, and it doesn't talk to other Subcontext widgets.

Stuck, or something missing?

Get in touch and a person on the team will help.

Contact us