Feature flags in the Web SDK

Pushwoosh.featureFlags gives your website the feature flags configured for the application in the Control Panel. Pushwoosh evaluates the flag rules on the server for the current device and user, and the SDK returns the result: whether the flag is on for this visitor and which property values apply.

Beta feature

Feature flags are in beta and available only on plans that include them. On other plans the server returns no flags, so every flag falls back to the default you pass in code.

Prerequisites

• Web SDK 3.94.1 or later, loaded from the Pushwoosh CDN as described in the Web SDK 3.0 guide. The web-push-notifications npm package doesn’t include feature flags yet. They become available with npm once version 3.94.1 or later is published there.
• At least one flag created in Audience → Feature Flags. You need its Key and the keys and types of its properties.

Read a flag

Read flags after the SDK is ready. Always pass a default: it applies until the SDK has flags for the page, and whenever the flag doesn’t exist, is archived, or the plan doesn’t include feature flags.

Pushwoosh.push(() => {
  const flags = Pushwoosh.featureFlags;

  const render = () => {
    const checkout = flags.get('new_checkout');
    if (checkout && checkout.enabled) {
      showNewCheckout({
        buttonColor: checkout.getString('button_color', 'blue'),
        maxItems: checkout.getNumber('max_items', 3),
      });
    } else {
      showOldCheckout();
    }
  };

  render();
  flags.addUpdateListener(render);
});

Once a version with feature flags is published to npm, use the Pushwoosh instance you created:

import { Pushwoosh } from 'web-push-notifications';

const pushwoosh = new Pushwoosh();
pushwoosh.push(['init', { applicationCode: 'XXXXX-XXXXX' /* ... */ }]);

pushwoosh.push(() => {
  const isNewCheckout = pushwoosh.featureFlags.isEnabled('new_checkout', false);
  // ...
});

The SDK makes no flag requests on a page until your code first calls get(), isEnabled(), refresh(), or addUpdateListener(), so pages that don’t use flags send no extra traffic.

What a flag returns

get(key) returns a FeatureFlag object, or null when the SDK has no flags for the page yet or the flag isn’t in the answer. An archived flag is not in the answer. The object has these fields:

Field	Type	Description
key	string	The flag key.
enabled	boolean	Whether the flag is on for this visitor.
ruleId	string	The rule that decided the result, for example r_1a2b3c4d. default when no rule matched the visitor, and an empty string when the flag is killed.

Read property values with the getter that matches the property type. Each getter returns your default when the property is missing or holds a value of another type. When the flag is off, the properties hold the default values set in the Control Panel.

Method	Returns
getString(property, defaultValue)	The value of a String property.
getNumber(property, defaultValue)	The value of a Number property.
getBool(property, defaultValue)	The value of a Boolean property.
getJson(property, defaultValue)	The value of a JSON property, as a parsed JSON value.
getProperties()	A copy of all property values of the flag.

isEnabled(key, defaultValue) is a shortcut for get(key)?.enabled, returning defaultValue when there is no flag.

Keep flags up to date

The SDK stores the flags in the browser’s IndexedDB for up to 24 hours, separately for each User ID, and refreshes them:

• on the first use on a page, when the stored flags are older than 15 minutes or missing;
• every hour while the page stays open;
• after the device registers, when the flags were requested before registration;
• right after the User ID changes. The stored flags of the previous user are discarded, so a new user never sees them.

To react to new values, register a listener. It’s called after a refresh that changed any flag value:

const onFlagsChanged = () => render();
Pushwoosh.featureFlags.addUpdateListener(onFlagsChanged);
// later
Pushwoosh.featureFlags.removeUpdateListener(onFlagsChanged);

To request the flags yourself, for example after an action that may move the visitor into a different segment, call refresh(). While the stored flags are valid, it sends at most one request per 5 minutes and resolves immediately within that window. The promise rejects when the request fails, and the stored flags stay in use.

try {
  await Pushwoosh.featureFlags.refresh();
} catch (error) {
  // the stored flags, or your defaults, stay in effect
}
render();

When Pushwoosh can’t match the visitor’s segments in time, it returns a partial answer. The SDK uses a partial answer only on the current page and only when it has no valid stored flags, and never stores it, so the next refresh brings the full answer.

When a flag is killed in the Control Panel, visitors get it off with default property values at the next refresh. When the SDK can’t reach the server, it keeps using the stored flags until they are 24 hours old, and your defaults after that.

Log impressions

An impression tells Pushwoosh that a visitor actually reached the code a flag controls, so you can compare visitors who got the feature with those who didn’t. Call logImpression(key) at the moment the visitor sees the feature or its old version, for both the enabled and the disabled branch, because visitors with the flag off are your comparison group:

const checkout = Pushwoosh.featureFlags.get('new_checkout');
if (checkout) {
  Pushwoosh.featureFlags.logImpression('new_checkout');
}

The SDK posts the PW_FeatureFlagImpression event with these attributes:

Attribute	Type	Value
flag_key	string	The flag key.
rule_id	string	The rule that decided the result, as in ruleId.
enabled	boolean	Whether the flag was on.

Create an event named PW_FeatureFlagImpression with these attributes in Audience → Events before you log impressions. The SDK sends one impression per flag, rule, and state on a page, and skips repeats from other tabs of the same browser for 30 minutes. logImpression() never rejects, and it sends nothing when there is no flag for the key.

Method reference

Pushwoosh.featureFlags has these methods:

Method	Description
get(key)	Returns the FeatureFlag for the key, or null. Reads the stored flags only and never waits for the network.
isEnabled(key, defaultValue)	Returns whether the flag is on, or defaultValue when there is no flag.
refresh()	Requests the flags, throttled to once per 5 minutes while the stored flags are valid. Returns a promise.
addUpdateListener(listener)	Calls listener after every refresh that changed a flag value.
removeUpdateListener(listener)	Removes a listener added with addUpdateListener.
logImpression(key)	Posts a PW_FeatureFlagImpression event for the flag’s current rule and state. Returns a promise.