Asynchronous Methods

Asynchronous versions of API methods.

Before the FS script is fully bootstrapped, all calls to the client API are enqueued to be processed when capture has begun. Once capture has begun, calls to the client API are immediately processed. Most of the actions in the API are "fire-and-forget" meaning they do not have a return value. In most cases, the caller is unconcerned with whether they succeed. However, a few API actions do have a return value. Additionally, it might be helpful in some cases for the caller to know whether a call to the FS API has succeeded.

For this reason, each API action has a corresponding asynchronous version that can be invoked by appending 'Async' to the action. For example, FS('getSession') becomes FS('getSessionAsync)'. The method returns a Promise-like object that resolves when the FS script has started and capture has begun. For the most part, the object returned from an async API action can be treated like a Promise. It can be async/await'ed and you can call .then on it. The main exception is that .catch won't work in older browsers that don't ship a global Promise polyfill.

Special Considerations

• The Promise returned by the FS api may be rejected. The following are examples of when a rejection might occur:
  • Malformed or missing configuration. (i.e. no _fs_org set)
  • The user is on an unsupported browser.
  • There was an error in the call to rec/settings or rec/page.
  • The call to rec/page returned a known error such as the org being over quota.
• In rare cases, the Promise might never resolve. For example, the FS script might get blocked by a user's ad blocker. We try to detect this using the .onerror method of script tag and reject the promise, but this event is not fired reliably in all browsers.
• For the reasons above, it is best to avoid writing blocking code using the FS async API. For example, don't do the following:

await FS('identifyAsync');
renderApplication();

• If you do not plan to act on the Promise, you should use the regular non-async version of the api to avoid unhandledrejection warnings in the console.

Example Invocation

Awaiting the session url

const url = await FS('getSessionAsync');

Log if an API action failed

try {
  await FS('trackEventAsync', {
    name: 'Big event',
    properties: { value_int: 42 }
  });
} catch (e) {
  console.error(e);
}