기능 플래그

기능 플래그(feature flag)는 앱이나 웹사이트의 기능을 켜고 끄는 스위치입니다. 새 릴리스 없이 Control Panel에서 전환합니다.

각 플래그마다 기능을 받을 대상을 선택합니다: 세그먼트의 사용자, 전체 사용자 중 일정 비율, 또는 둘 다입니다. 예를 들어 새 화면을 먼저 사용자의 10%에게 보여 준 다음 비율을 높입니다. 문제가 생기면 모두에게 중지 버튼으로 모든 사용자에 대해 기능을 끌 수 있습니다. 플래그에는 버튼 색상이나 할인 한도처럼 대상별로 설정하는 속성도 담을 수 있습니다.

시작하기 전에

요금제: 기능 플래그는 이를 포함하는 요금제에서만 사용할 수 있습니다. 다른 요금제에서는 오디언스 메뉴에 기능 플래그가 표시되지 않습니다. 사용하려면 담당 어카운트 매니저에게 문의하세요.
접근 권한: 기능 플래그는 볼 수 있는 모든 애플리케이션에 표시됩니다. 플래그를 만들고 변경하려면 애플리케이션 수정 권한이 필요하며, 또는 이 애플리케이션의 앱별 권한에서 같은 권한이 있어야 합니다.
개발자 설정: 플래그는 개발자가 앱이나 웹사이트 코드에서 키로 플래그를 읽은 후에야 사용자에게 적용됩니다. 개발자에게는 Web SDK 3.94.1 이상, Android SDK 6.16.0 이상 또는 iOS SDK 7.2.10 이상이 필요합니다. 아직 플래그가 없는 애플리케이션에서는 기능 플래그 페이지에 Web, Android, iOS용 바로 사용할 수 있는 코드 샘플이 표시됩니다. 플래그 키와 함께 이 샘플을 개발자에게 전달하세요. 개발자에게 Web SDK 가이드, Android SDK 가이드 또는 iOS SDK 가이드를 공유하세요.

요금제에 기능 플래그가 더 이상 포함되지 않으면 기기는 플래그를 받지 않고, 앱이나 웹사이트는 코드에 설정된 값을 사용합니다. 이때 플래그를 만들거나 복원하면 현재 요금제에서는 기능 플래그를 사용할 수 없습니다 메시지와 함께 실패합니다. 예를 들어 요금제가 바뀌기 전에 열어 둔 Control Panel 탭에서 이런 일이 발생합니다.

플래그가 각 사용자가 받을 결과를 결정하는 방식

모든 플래그에는 규칙 목록이 있습니다. 각 규칙에는 세그먼트, 플래그가 켜지는 사용자 비율(배포 비율, %), 그리고 선택 사항인 속성 값이 있습니다. Pushwoosh는 기기마다 규칙을 위에서 아래로 확인합니다:

기기가 일치하는 세그먼트를 가진 첫 번째 규칙이 결정합니다. 세그먼트가 없는 규칙은 모든 기기와 일치합니다.
규칙의 배포 비율, % 값이 이 사용자에게 플래그가 켜지는지 결정합니다. 20%이면 사용자 10명 중 2명이 플래그를 받습니다.
플래그가 켜진 사용자는 해당 규칙에 설정된 속성 값을 받습니다. 플래그가 꺼진 사용자는 기본 속성 값을 받습니다.

기기가 어떤 규칙과 일치하면, 그 규칙이 해당 기기에 대해 플래그를 끄더라도 이후 규칙은 건너뜁니다. 어떤 규칙과도 일치하지 않는 기기는 플래그가 꺼진 상태로 받습니다.

사용자는 방문할 때마다 같은 결과를 받습니다. 같은 User ID로 로그인한 기기들은 같은 규칙과 일치할 때 같은 결과를 받습니다. Pushwoosh가 기기마다 세그먼트를 확인하기 때문입니다. Pushwoosh는 User ID로 사용자를 식별하며, User ID가 설정되지 않은 경우 기기 ID로 식별합니다. 비율을 높이면 이미 플래그를 받은 사용자는 그대로 유지되고 새로운 사용자가 추가됩니다.

플래그 만들기

오디언스 → 기능 플래그로 이동합니다.
기능 플래그 만들기를 클릭합니다.
키를 입력합니다. 예: new_checkout. 키는 원하는 아무 이름이나 될 수 있지만, 개발자는 대소문자까지 포함해 정확히 이 키로 코드에서 플래그를 읽습니다. 플래그를 저장하기 전에 개발자와 키를 합의하세요.
팀이 플래그가 무엇을 제어하는지 알 수 있도록 이름과 선택 사항인 설명을 입력합니다.

키는 다음 규칙을 따릅니다:

라틴 문자, 숫자, _, ., -, 최대 58자.
나중에 키를 변경할 수 없습니다.
애플리케이션의 다른 플래그가 이미 사용하는 키는 보관된 플래그의 키라도 다시 사용할 수 없으며, New_Checkout과 new_checkout처럼 대소문자만 다른 키도 사용할 수 없습니다.

속성 추가

속성은 앱이나 웹사이트가 플래그에서 읽는 값입니다. 예를 들어 배너 텍스트나 추천 블록의 항목 수입니다. 플래그가 기능을 켜고 끄기만 한다면 이 단계를 건너뛰세요.

속성에서 속성 추가를 클릭합니다.
속성 키를 입력합니다. 예: button_color. 라틴 문자, 숫자, _를 사용하며 최대 64자입니다. 속성 키는 원하는 아무 이름이나 될 수 있지만, 개발자는 대소문자까지 포함해 정확히 이 키로 코드에서 값을 읽습니다. 플래그를 저장하기 전에 개발자와 키를 합의하세요.
유형을 선택합니다: 문자열, 숫자, 불리언, JSON. 플래그를 저장한 후에는 유형을 변경할 수 없습니다.
기본값을 입력합니다. 플래그가 꺼진 사용자는 이 값을 받습니다.

플래그 하나에 속성을 최대 50개까지 둘 수 있습니다.

키, 이름, 설명과 두 개의 속성(String 유형의 button_color, Boolean 유형의 show_apple_pay)이 있는 기능 플래그 양식

규칙 추가

규칙에서 규칙 추가를 클릭합니다.
규칙 이름을 입력합니다. 예: Paying customers.
세그먼트에서 규칙을 적용할 대상을 선택합니다. 비워 두면 모든 사용자에게 규칙이 적용됩니다.
배포 비율, % 필드에 세그먼트 중 플래그가 켜질 비율을 0에서 100 사이로, 소수점 이하 두 자리까지 입력합니다.
이 규칙으로 플래그가 켜진 사용자를 위한 값에서 이 사용자들에게 기본값과 달라야 하는 속성을 변경합니다. 변경하지 않은 속성은 기본값을 유지합니다.
다른 대상을 추가하려면 단계를 반복합니다. 첫 번째로 일치하는 규칙이 결정하므로 위로와 아래로로 순서를 변경하세요.

플래그 하나에 규칙을 최대 10개까지 둘 수 있습니다.

각 규칙의 배포 비율, % 아래에는 해당 규칙이 플래그를 켜는 대략적인 기기 수가 표시됩니다. 예: ≈ 1,200대. Pushwoosh는 규칙 세그먼트의 크기에 비율을 곱합니다. 세그먼트가 없는 규칙은 애플리케이션의 모든 기기를 기준으로 합니다. 앞선 규칙과 일치하는 기기는 그 규칙에서 멈추므로, 이 숫자는 규칙이 도달할 수 있는 최대치로 보세요.

기능 플래그의 Rule 1: Purchased something 세그먼트에 대한 Paying customers, 100%, button_color는 green, show_apple_pay는 true로 설정됨

예를 들어 모든 유료 고객과 나머지 사용자의 20%에게 새 결제 화면을 제공하려면 규칙 두 개를 만듭니다:

규칙	세그먼트	배포 비율, %	이 규칙으로 플래그가 켜진 사용자를 위한 값
Paying customers	Purchased something	100	`button_color` = `green`, `show_apple_pay` = `true`
Everyone else	—	20	`button_color` = `orange`

플래그 저장

저장을 클릭합니다. 플래그는 활성 상태로 생성되며, 기기는 다음에 플래그를 확인할 때 이를 받습니다.

플래그 관리

플래그 목록에는 각 플래그의 이름, 키, 상태, 규칙 수, 마지막 업데이트 시간이 표시됩니다. 보관된 플래그를 보려면 보관된 항목 표시를 켭니다. 플래그를 열려면 플래그 이름을 클릭합니다. 목록 상단과 각 플래그 상단의 SDK 지원 블록은 기기가 SDK 버전을 보고하는 경우, 애플리케이션 기기 중 이전 SDK를 사용하는 기기의 비율을 보여 줍니다. 이런 기기는 사용자가 앱을 업데이트할 때까지 플래그를 받지 않습니다.

플래그는 다음 세 가지 상태 중 하나입니다:

상태	사용자가 받는 결과	작업
활성	플래그가 규칙에 따라 작동합니다.	다시 섞기, 모두에게 중지, 보관
중지됨	모든 사용자에게 플래그가 꺼지고 기본 속성 값이 적용됩니다. 규칙과 속성은 유지됩니다.	다시 켜기, 보관
보관됨	기기가 더 이상 플래그를 받지 않으므로, 코드는 개발자가 코드에 설정한 값을 사용합니다.	복원

플래그 변경

플래그를 엽니다.
이름, 설명, 속성 또는 규칙을 편집합니다.
저장을 클릭합니다.
규칙이나 기본 속성 값을 변경했다면 변경 사항 검토 대화 상자에 기기에 어떤 일이 생기는지 표시됩니다. 내용을 확인하고 저장을 클릭합니다.

대화 상자에는 변경 사항마다 한 줄이 표시됩니다:

규칙의 배포 비율: 플래그를 새로 받게 되는 대략적인 기기 수, 또는 플래그를 잃는 기기 수.
규칙의 값: 새 값을 받는 대략적인 기기 수와 각 속성의 이전 값과 새 값.
새로 추가되거나 삭제된 규칙, 다른 세그먼트 또는 새 규칙 순서: 기기가 어디로 이동하는지. 예를 들어 삭제된 규칙의 기기는 일치하는 다음 규칙으로 이동합니다.
기본값: 플래그가 꺼진 기기가 받는 이전 값과 새 값.

이름이나 설명만 변경한 경우에는 대화 상자 없이 저장됩니다.

기능을 점진적으로 출시하려면 규칙의 배포 비율, % 값을 단계적으로 높이세요.

편집하는 동안 다른 사람이 플래그를 저장했다면, Control Panel은 그 사람의 변경 사항을 덮어쓰지 않고 플래그를 다시 불러오라고 요청합니다. 새로고침을 클릭하고 변경 사항을 다시 적용하세요.

모든 사용자에 대해 플래그 끄기

기능이 문제를 일으켜 모든 사용자에 대해 중지해야 할 때 모두에게 중지를 사용합니다:

플래그를 열고 모두에게 중지를 클릭합니다.
확인합니다. 모든 기기는 다음에 플래그를 확인할 때 기본 속성 값과 함께 플래그가 꺼진 상태로 받습니다.

웹사이트나 앱이 열려 있는 동안 기기는 1시간 이내에 변경 사항을 받습니다. Web SDK, Android SDK, iOS SDK가 플래그를 확인하는 방식을 참조하세요.

기존 규칙 그대로 플래그를 다시 켜려면 다시 켜기를 클릭합니다.

다른 사용자 표본 선택

다시 섞기는 모든 사용자를 새 그룹에 배치하므로, 같은 비율의 사용자가 다른 사람들로 구성됩니다. 새 테스트를 시작할 때처럼 새로운 표본이 필요할 때 사용하세요.

활성 플래그를 열고 다시 섞기를 클릭합니다.
확인합니다. 비율은 그대로 유지되면서, 플래그가 켜져 있던 일부 사용자는 플래그를 잃고 다른 사용자는 다음에 기기가 플래그를 확인할 때 플래그를 받습니다.

플래그 보관 및 복원

기능이 완전히 출시되었거나 코드에서 제거되었으면 플래그를 보관하세요. 보관된 플래그는 요금제의 애플리케이션당 플래그 한도에 포함되지 않으며, 해당 키는 계속 예약된 상태로 유지됩니다.

플래그를 열고 보관을 클릭합니다.
확인합니다.

보관된 플래그는 편집할 수 없습니다. 다시 가져오려면 목록에서 보관된 항목 표시를 켜고 플래그를 연 다음 복원을 클릭합니다. 복원된 플래그는 중지됨 상태로 돌아오므로 스스로 사용자에게 전달되지 않습니다. 준비가 되면 다시 켜기를 클릭하세요.

플래그를 변경한 사람 확인

변경 기록에는 플래그의 저장된 모든 버전이 표시됩니다: 무엇이 바뀌었는지, 누가 바꿨는지, 언제 바꿨는지. 플래그를 열 수 있는 사람은 누구나 기록을 볼 수 있습니다.

기록은 2026년 10월 13일 이후의 변경 사항부터 저장됩니다. 기록된 변경 사항이 없는 플래그에는 아직 변경 사항이 없습니다가 표시됩니다. 그 날짜 이전에 만든 플래그의 경우 가장 오래된 항목에는 변경 목록이 표시되지 않습니다. 비교할 이전 버전이 없기 때문입니다.

플래그를 엽니다.
기록을 클릭합니다.

변경 기록 패널에는 플래그의 버전이 최신순으로 표시됩니다. 각 항목에는 다음이 표시됩니다:

작업. 예: 수정됨.
변경한 사람: 사용자 이메일 또는 변경이 들어온 API 토큰. 예: API 토큰 “Release pipeline”, 이름이 없는 토큰은 API 토큰.
날짜와 시간.
버전 번호. 예: v4.

기능 플래그의 변경 기록 패널, 최신순: 작업, 사용자 이메일 또는 API 토큰, 날짜와 시간, 버전

이전 항목을 불러오려면 더 보기를 클릭합니다.

작업	발생한 일
생성됨	플래그가 생성되었습니다.
수정됨	누군가 플래그 변경 사항을 저장했습니다.
롤아웃 변경	API 또는 MCP 서버를 통해 규칙 하나의 배포 비율이 변경되었습니다. Control Panel에서는 배포 비율 변경이 수정됨으로 저장됩니다.
중지됨	누군가 모두에게 중지를 클릭했습니다.
다시 켜짐	누군가 다시 켜기를 클릭했습니다.
보관됨	플래그가 보관되었습니다.
복원됨	플래그가 보관함에서 복원되었습니다.
사용자 재배정	누군가 다시 섞기를 클릭했습니다.

각 항목 아래에는 변경된 내용이 변경 전후 값으로 표시됩니다: 이름, 설명, 상태, 속성, 규칙 순서, 그리고 추가, 삭제 또는 변경된 각 규칙. 변경된 규칙은 달라진 필드만 표시합니다: 이름, 세그먼트, 롤아웃 또는 값. 세그먼트가 없는 규칙에는 모든 사용자가 표시됩니다.

플래그로 사용자 세그먼트 만들기

세그먼트의 기능 플래그 조건은 플래그를 켜진 상태로 받았거나, 꺼진 상태로 받았거나, 플래그 규칙 중 하나와 일치했거나, 플래그가 제어하는 앱 영역에 도달한 기기를 찾습니다. 새 기능을 보는 사용자에게 피드백을 요청하는 등 메시지를 보내거나, 이들을 대상으로 Journey를 만들 때 사용하세요.

세그먼트를 생성하는 방법에 설명된 대로 세그먼트 빌더를 엽니다.
조건 목록에서 기능 플래그를 클릭합니다.
기능 플래그 선택… 목록에서 플래그를 선택합니다. 보관된 플래그는 목록에 없습니다.
상태를 선택합니다:
- 켜짐: 플래그를 켜진 상태로 받은 기기.
- 꺼짐: 플래그를 꺼진 상태로 받은 기기.
- 규칙에 포함: 규칙의 세그먼트와 일치한 기기. 규칙의 배포 비율, % 값이 플래그를 켰는지와 관계없습니다. 규칙 선택… 목록에서 규칙을 선택합니다.
- 기능을 봄 (30일): 최근 30일 동안 플래그 노출을 한 번 이상 보낸 기기, 즉 앱이 이 플래그 키에 대해 logImpression을 호출한 기기. 기능에 도달한 사용자 찾기를 참조하세요.

기능 플래그는 기능 플래그가 포함된 요금제에서만 세그먼트 빌더에 표시됩니다. 태그 조건만 포함할 수 있는 High Speed Delivery 세그먼트에서는 사용할 수 없습니다.

각 상태에 포함되는 기기

기기의 상태는 기기가 마지막으로 받은 플래그와 플래그의 현재 상태를 따릅니다:

예를 들어 SDK가 플래그를 읽지 않아 플래그를 한 번도 요청하지 않은 기기는 어느 상태에도 포함되지 않습니다.
규칙이나 규칙의 배포 비율, % 값을 변경한 후에는 기기가 플래그를 다시 요청할 때만 다른 상태로 이동합니다.
플래그를 중지하거나 보관하면 기기가 플래그를 다시 요청하기를 기다리지 않고 약 10초 이내에 켜짐과 규칙에 포함이 비워집니다. 이후 꺼짐에는 플래그를 한 번이라도 받은 모든 기기가 포함됩니다.

기능에 도달한 사용자 찾기

켜진 기능을 본 사용자를 찾으려면:

플래그에 대해 기능을 봄 (30일) 조건을 추가합니다.
같은 플래그에 대해 켜짐을 추가하고 두 조건을 AND로 연결합니다.

기능을 봄 (30일) 조건은 플래그가 켜져 있었는지 꺼져 있었는지와 관계없이, 플래그가 제어하는 화면이나 코드에 도달한 사용자와 일치합니다. 그래서 켜짐을 추가합니다: 새 버전을 받은 사용자만 남기기 때문입니다. 결과는 근사치이며 정확하지는 않습니다. 켜짐은 기기가 마지막으로 받은 플래그를 반영하며, 노출은 플래그가 꺼져 있던 이전 방문에서 발생했을 수 있습니다.

앱이 노출을 기록하지 않으면 세그먼트는 비어 있습니다. 노출을 기록하는 방법은 Web SDK, Android SDK 또는 iOS SDK 가이드의 Log impressions를 참조하세요.

플래그를 중지하거나 보관해도 이 상태는 비워지지 않습니다. 기기는 마지막 노출 후 30일이 지나면 이 상태에서 벗어납니다.

Journey에서 플래그 세그먼트 사용

기능 플래그 조건이 있는 세그먼트는 오디언스 기반 진입과 조건 분기에서 작동합니다. 예를 들어 새 결제 화면을 받은 사용자와 받지 않은 사용자를 나누고 각 그룹에 맞는 메시지를 보낼 수 있습니다.

한도

Control Panel과 API는 플래그를 저장할 때 다음 한도를 적용합니다:

한도	값
플래그당 규칙 수	10
플래그당 속성 수	50
플래그 하나의 속성 크기(키, 유형, 기본값)	10,000바이트
JSON 값의 중첩 깊이	5단계
애플리케이션당 플래그 수	요금제에 따라 정해지며, 보관된 플래그는 포함되지 않음
기기 하나가 애플리케이션의 모든 플래그에 대해 받는 데이터	64 KB

API로 플래그 관리

개발자는 Feature Flags API로 자체 시스템에서 플래그를 만들고 변경할 수 있으며, Pushwoosh MCP 서버를 통해 연결된 AI 어시스턴트도 같은 작업으로 플래그를 관리할 수 있습니다.