Web SDK의 기능 플래그

Pushwoosh.featureFlags는 Control Panel에서 애플리케이션에 구성된 기능 플래그를 웹사이트에 제공합니다. Pushwoosh는 현재 기기와 사용자에 대해 서버에서 플래그 규칙을 평가하고, SDK는 그 결과를 반환합니다. 즉, 이 방문자에게 플래그가 켜져 있는지와 어떤 속성 값이 적용되는지를 반환합니다.

사전 요구 사항

Web SDK 3.0 가이드에 설명된 대로 Pushwoosh CDN에서 로드한 Web SDK 3.94.1 이상, 또는 web-push-notifications npm 패키지 3.95.0 이상.
Audience → Feature Flags에서 생성한 플래그가 하나 이상 있어야 합니다. 해당 플래그의 Key와 속성의 키 및 유형이 필요합니다. 키는 대소문자를 포함해 그곳에 표시된 그대로 사용하세요. 예를 들어 get('New_Checkout')은 키가 new_checkout인 플래그를 찾지 못합니다.

플래그 읽기

SDK가 준비된 후 플래그를 읽으세요. 항상 기본값을 전달하세요. 기본값은 SDK가 페이지의 플래그를 가져올 때까지 적용되며, 플래그가 존재하지 않거나 보관되었거나 요금제에 기능 플래그가 포함되지 않은 경우에도 적용됩니다.

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);
});

npm 패키지를 사용하는 경우 생성한 Pushwoosh 인스턴스를 사용하세요.

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);
  // ...
});

코드에서 get(), isEnabled(), refresh() 또는 addUpdateListener()를 처음 호출하기 전까지 SDK는 페이지에서 플래그 요청을 보내지 않으므로, 플래그를 사용하지 않는 페이지에서는 추가 트래픽이 발생하지 않습니다.

플래그가 반환하는 내용

get(key)는 FeatureFlag 객체를 반환하며, SDK가 아직 페이지의 플래그를 가지고 있지 않거나 응답에 플래그가 없으면 null을 반환합니다. 보관된 플래그는 응답에 포함되지 않습니다. 객체에는 다음 필드가 있습니다.

필드	유형	설명
`key`	string	플래그 키입니다.
`enabled`	boolean	이 방문자에게 플래그가 켜져 있는지 여부입니다.
`ruleId`	string	결과를 결정한 규칙입니다(예: `r_1a2b3c4d`). 방문자와 일치하는 규칙이 없으면 `default`이고, 플래그가 강제 종료(kill)된 경우 빈 문자열입니다.

속성 유형에 맞는 getter로 속성 값을 읽으세요. 각 getter는 속성이 없거나 다른 유형의 값을 가지고 있으면 지정한 기본값을 반환합니다. 플래그가 꺼져 있으면 속성에는 Control Panel에서 설정한 기본값이 들어 있습니다.

메서드	반환값
`getString(property, defaultValue)`	String 속성의 값입니다.
`getNumber(property, defaultValue)`	Number 속성의 값입니다.
`getBool(property, defaultValue)`	Boolean 속성의 값입니다.
`getJson(property, defaultValue)`	JSON 속성의 값으로, 파싱된 JSON 값입니다.
`getProperties()`	플래그의 모든 속성 값 사본입니다.

isEnabled(key, defaultValue)는 get(key)?.enabled의 단축 메서드이며, 플래그가 없으면 defaultValue를 반환합니다.

플래그를 최신 상태로 유지하기

SDK는 마지막 응답을 브라우저의 IndexedDB에 최대 24시간 동안 저장합니다. 저장된 플래그는 요청 시의 User ID에 대해서만 유효합니다. SDK는 다음 경우에 플래그를 새로 고칩니다.

페이지에서 처음 사용할 때, 저장된 플래그가 15분보다 오래되었거나 없는 경우
페이지가 열려 있는 동안 1시간마다
기기가 등록된 후, 등록 전에 플래그를 요청한 경우
User ID가 변경된 직후. 이전 사용자의 저장된 플래그는 삭제되므로 새 사용자는 이를 볼 수 없습니다.

새 값에 반응하려면 리스너를 등록하세요. 리스너는 플래그 값을 변경한 새로 고침 후에 호출됩니다.

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

방문자를 다른 Segment로 이동시킬 수 있는 작업 이후처럼 플래그를 직접 요청하려면 refresh()를 호출하세요. 저장된 플래그가 유효한 동안에는 5분에 최대 한 번만 요청을 보내며, 그 기간 안에서는 즉시 완료됩니다. 요청이 실패하면 promise가 거부되고, 저장된 플래그가 계속 사용됩니다.

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

Pushwoosh가 방문자의 Segment를 제때 매칭하지 못하면 부분 응답을 반환합니다. SDK는 이 응답을 현재 페이지에서만, 유효한 저장된 플래그가 없을 때만 사용하며, 절대 저장하지 않습니다. 다음 새로 고침에서 전체 응답을 가져옵니다.

Control Panel에서 플래그를 강제 종료(kill)하면 방문자는 다음 새로 고침 시 해당 플래그를 기본 속성 값과 함께 꺼진 상태로 받습니다. SDK가 서버에 연결할 수 없으면 저장된 플래그가 24시간이 될 때까지 계속 사용하고, 그 이후에는 지정한 기본값을 사용합니다.

노출 기록하기

노출(impression)은 방문자가 플래그가 제어하는 코드에 실제로 도달했음을 Pushwoosh에 알려 주므로, 기능을 받은 방문자와 받지 않은 방문자를 비교할 수 있습니다. 방문자가 기능 또는 이전 버전을 보는 시점에 logImpression(key)를 호출하세요. 플래그가 꺼진 방문자가 비교 그룹이므로 켜진 분기와 꺼진 분기 모두에서 호출해야 합니다.

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

SDK는 다음 속성과 함께 PW_FeatureFlagImpression 이벤트를 전송합니다.

속성	유형	값
`flag_key`	string	플래그 키입니다.
`rule_id`	string	결과를 결정한 규칙으로, `ruleId`와 같습니다.
`enabled`	boolean	플래그가 켜져 있었는지 여부입니다.

첫 번째 노출이 도착하면 Pushwoosh가 이러한 속성과 함께 PW_FeatureFlagImpression을 Audience → Events에 추가하므로 이벤트를 미리 만들 필요가 없습니다. SDK는 한 페이지에서 플래그, 규칙, 상태별로 노출을 한 번만 전송하며, 30분 동안 같은 브라우저의 다른 탭에서 발생한 중복을 건너뜁니다. logImpression()은 절대 거부되지 않으며, 해당 키에 대한 플래그가 없으면 아무것도 전송하지 않습니다.

노출을 활용하면 마케터는 해당 기능에 도달한 방문자의 세그먼트도 만들 수 있습니다. 기능 플래그 조건의 기능을 봄 (30일) 상태를 사용하세요.

메서드 참조

Pushwoosh.featureFlags에는 다음 메서드가 있습니다.

메서드	설명
`get(key)`	키에 해당하는 `FeatureFlag` 또는 `null`을 반환합니다. 저장된 플래그만 읽으며 네트워크를 기다리지 않습니다.
`isEnabled(key, defaultValue)`	플래그가 켜져 있는지 여부를 반환하며, 플래그가 없으면 `defaultValue`를 반환합니다.
`refresh()`	플래그를 요청하며, 저장된 플래그가 유효한 동안에는 5분에 한 번으로 제한됩니다. promise를 반환합니다.
`addUpdateListener(listener)`	플래그 값을 변경한 모든 새로 고침 후에 `listener`를 호출합니다.
`removeUpdateListener(listener)`	`addUpdateListener`로 추가한 리스너를 제거합니다.
`logImpression(key)`	플래그의 현재 규칙과 상태에 대한 `PW_FeatureFlagImpression` 이벤트를 전송합니다. promise를 반환합니다.