통신사 가입자 데이터 및 세그먼트 시작하기

이 가이드는 Pushwoosh에서 통신사 가입자 프로필을 설정하고, 이를 번들 만료 알림, 잔액 부족 경고, 충전 확인, 로밍 환영 메시지와 같은 실제 작동하는 세그먼트로 전환하는 방법을 설명합니다. 모든 섹션을 완료하면 처음 구축하는 세그먼트가 0이 아닌 잠재고객을 반환하므로 지원팀에 문의할 필요가 없습니다.

가장 흔한 실수는 태그 유형입니다. 정수(Integer) 태그에 저장된 날짜는 태그 목록에서는 정상적으로 보이지만, 모든 날짜 세그먼트에서 조용히 0명의 사용자를 반환하게 만듭니다. 먼저 유형을 선택한 다음 데이터를 로드하세요.

전제 조건

Pushwoosh 계정의 애플리케이션에 SDK가 통합되었거나 API를 통해 기기가 등록되어 있어야 합니다.
태그 설정 권한이 있는 API 액세스 토큰.
서버 간 업데이트 작업을 위한 개발자 지원.
Pushwoosh에 매핑할 수 있는 가입자 식별자: User ID(일반적으로 MSISDN, 즉 국제 형식의 가입자 전화번호 또는 내부 가입자 ID) 또는 기기 HWID.

통신사 가입자 프로필의 모습

아래 표는 표준 통신 시나리오를 다루는 태그 목록입니다. 첫 데이터 로드 전에 정확히 이 유형들로 생성하세요.

태그	유형	예시 값	용도
`msisdn`	String	`923001234567`	신원 확인 및 SMS 타겟팅
`tariff_plan`	String	`Gold Postpaid`	요금제별 맞춤 혜택
`prepaid_postpaid`	String	`prepaid`	청구 모델별로 기반 분리
`balance`	Integer	`50`	잔액 부족 알림
`bundle_id`	String	`DATA_5GB_30D`	알림의 대상이 되는 번들
`bundle_expiry_date`	Date	`2026-09-20 21:00:00`	번들 만료 알림
`roaming_status`	Boolean	`true`	로밍 환영 메시지 및 로밍 요금 경고

이 표의 두 행이 시나리오의 작동 여부를 결정합니다.

bundle_expiry_date는 Date 태그여야 합니다. Date 태그만이 매일 밤 세그먼트를 재계산하지 않고도 “번들이 3일 후에 만료됩니다”를 표현하는 N일 후와 M일 후 사이와 같은 상대 연산자를 사용할 수 있습니다.
bundle_id는 만료일과 별도로 유지됩니다. 한 태그는 날짜를, 다른 태그는 해당 번들이 어떤 것인지에 대한 정보를 담습니다. 두 정보를 한 태그에 저장하면 세그먼트 내에서 문자열을 파싱해야 하는데, 세그먼트 빌더는 이 기능을 지원하지 않습니다.

첫 업로드 전에 태그 유형을 결정해야 하는 이유

태그는 값이 처음 도착할 때 자동으로 생성되며, 유형은 첫 번째 값에서 추론됩니다. 정수는 Integer, 소수점이 있는 숫자는 Price, 문자열은 String(또는 2024-10-02 22:11과 같이 인식되는 날짜-시간 형식과 일치하면 Date), 배열은 List, true/false는 Boolean이 됩니다.

통신 데이터에서는 만료일이 보통 Unix 타임스탬프로 전송되기 때문에 이 추론이 실패합니다:

bundle_expiry_date를 숫자 1758393600으로 보냅니다. 이는 정수이므로 태그는 Integer 태그로 생성됩니다. 값은 올바르게 로드되고 태그는 정상적으로 보이지만, 날짜 연산자는 제공되지 않습니다.
태그가 이미 Integer로 존재하고 나중에 "2026-09-20"을 보내도록 전환합니다. 이 값은 더 이상 숫자로 파싱되지 않으므로 오류 없이 삭제됩니다. API는 여전히 성공으로 응답하고, 기기는 이전 값을 유지하거나 아무 값도 갖지 않게 됩니다.

두 경우 모두 세그먼트가 0명의 사용자를 반환하고, 이를 설명할 오류 메시지는 어디에도 없습니다.

태그 유형은 생성 후 변경할 수 없습니다. 잘못된 유형을 수정하려면 올바른 유형으로 새 태그를 만들고 값을 다시 로드해야 합니다. 이전 태그는 삭제할 때까지 목록에 남아 있습니다.

두 경우를 모두 방지하려면 직접 유형을 설정하세요:

Control Panel의 Tags 페이지를 엽니다.
태그 생성을 클릭합니다.
태그 이름을 입력하고 목록에서 유형을 선택합니다. 첫 업로드 전에 위 표의 모든 태그에 대해 이 과정을 반복합니다.
bulkSetTags에서 create_missing_tags: false를 보냅니다. 그러면 누락된 태그는 추측된 유형으로 생성되는 대신 오류를 반환합니다.

서버 간 프로필 업데이트 방법

통신 프로필 데이터는 매일 변경되므로 모바일 SDK에서가 아닌 배치 작업으로 로드됩니다.

귀사 측에서 일일 델타를 구축합니다: 마지막 실행 이후 잔액, 번들 또는 로밍 상태가 변경된 가입자. 매일 밤 전체 기반을 다시 로드하는 것은 거의 필요하지 않으며 요청량을 소모합니다.
MSISDN이 User ID인 경우 user_id로, 그렇지 않은 경우 hwid로 기기를 지정하여 bulkSetTags에 배치를 보냅니다. 하나의 요청에 많은 기기를 담을 수 있으며, 이 메서드는 최소 50개의 기기를 예상합니다. 단일 가입자의 경우 setTags를 대신 사용하세요.
작업이 완료될 때까지 반환된 request_id를 bulkSetTags status로 폴링합니다. ?detailed=true로 요청하고 결과를 기록하세요. 완료된 작업이 모든 값이 수락되었음을 의미하지는 않기 때문입니다.
실패한 배치는 동일한 페이로드로 재시도하세요. 태그 설정은 멱등성을 가집니다: 동일한 값을 두 번 보내도 동일한 프로필이 남습니다.

{
  "application": "XXXXX-XXXXX",
  "auth": "your API access token",
  "create_missing_tags": false,
  "devices": [{
    "user_id": "923001234567",
    "tags": {
      "bundle_id": "DATA_5GB_30D",
      "bundle_expiry_date": "2026-09-20 21:00:00",
      "balance": 50,
      "roaming_status": false
    }
  }]
}

Date 태그가 허용하는 날짜 형식

Date 태그는 Unix epoch 타임스탬프를 초 단위로 저장합니다. 다음 중 하나를 보내세요:

초 단위의 epoch 값(숫자): 1758393600.
구분자가 있는 날짜-시간 문자열: 2026-09-20 21:00:00, 2026-09-20 21:00, 또는 2026-09-20. 시간이 없는 날짜는 자정을 의미합니다.
오프셋이 있는 ISO 8601 문자열: 2026-09-20T21:00:00+05:00.

두 가지 형식은 대부분의 통합에서 예상치 못한 방식으로 작동합니다:

시간대 없는 문자열은 UTC로 읽힙니다. 현지 시간으로 읽히지 않습니다. 카라치에서 21:00에 만료되는 번들은 2026-09-20T21:00:00+05:00 또는 해당 epoch 값입니다. 2026-09-20 21:00:00은 실제 시간으로 3시간 이르므로, 가입자가 일일 알림 웨이브 사이를 이동하게 됩니다.
숫자 문자열은 날짜가 아닌 epoch 값입니다. "20260920"은 2026년 9월 20일이 아니라 1970년을 가리키는 epoch 타임스탬프입니다. 실제 epoch 값을 보내거나 구분자가 있는 문자열을 보내세요.

허용된 형식과 일치하지 않는 값은 요청을 실패시키지 않고 버려집니다. 이것이 위 3단계에서 HTTP 상태만 확인하는 대신 작업 결과를 확인하는 이유입니다.

세그먼트 레시피

아래 각 레시피는 하나의 세그먼트입니다. Segments 섹션을 열고 세그먼트 생성을 클릭하여 빌더를 연 다음, 나열된 필터를 추가하세요. 전체 빌더 연습은 태그로 세그먼트 만들기를 참조하세요.

3일 후 번들 만료

현재 번들이 3일 후에 만료되는 가입자를 대상으로 하여, 갱신이 여전히 의미 있을 때 알림이 도착하도록 합니다.

태그: bundle_expiry_date
연산자: 연산자 목록을 열고 상대 날짜 섹션으로 이동하여 N일 후와 M일 후 사이를 선택합니다.
값: 3과 3

마지막 날 알림을 위해서는 두 값을 모두 1과 1로 변경하세요. 메시지에서 특정 번들을 언급할 경우 bundle_id에 대한 두 번째 필터를 추가하세요.

잔액 부족

다음 갱신 비용을 지불할 수 없는 선불 가입자를 대상으로 합니다.

태그: balance, 연산자 이하, 값 50
태그: prepaid_postpaid, 연산자 같음, 값 prepaid

두 조건 모두 동일한 그룹에 그리고로 결합됩니다.

로밍 진입

현재 해외에 있는 가입자를 대상으로 현지 요금이 포함된 환영 메시지를 보냅니다.

태그: roaming_status, 연산자 예

태그 기반 세그먼트는 컴파일 시점의 상태를 반영합니다. 로밍이 시작되는 순간 메시지가 발송되어야 하는 경우, 이 세그먼트로 보내는 대신 로밍 이벤트에서 고객 여정을 트리거하세요.

충전 확인 및 기타 반응

충전을 확인하는 것은 잠재고객을 컴파일하는 것이 아니라 단일 가입자의 행동에 대한 반응입니다. 청구 시스템에서 postEvent로 사용자 지정 이벤트를 보내고, 이를 통해 고객 여정을 시작하세요. 번들 구매 및 요금제 변경에도 동일하게 적용됩니다.

세그먼트가 0명의 사용자를 반환하는 경우

이 순서대로 확인하세요. 처음 세 가지가 지원팀에 보고된 대부분의 사례를 해결합니다.

Tags 페이지에서 태그 유형을 확인하세요. bundle_expiry_date가 Integer인 경우, 날짜 연산자가 적용되지 않았고 세그먼트는 숫자를 비교했습니다. Date 태그를 만들고 값을 다시 로드하세요.
값이 실제로 도착했는지 확인하세요. User Explorer를 열고, 배치에 포함된 것으로 아는 가입자를 찾아 태그를 확인하세요. 성공적인 작업 후 태그가 비어 있다면, 값이 형식 때문에 거부된 것입니다. 가장 흔한 경우는 숫자만 있는 문자열이나 레이아웃과 일치하지 않는 날짜입니다.
연산자 섹션을 확인하세요. 기념일 아래의 N일 후는 연도를 무시합니다. 상대 날짜 아래의 N일 후와 M일 후 사이는 연도를 고려합니다.
시간대를 확인하세요. 오프셋 없이 전송된 만료 타임스탬프는 UTC로 읽히며, 이로 인해 가입자가 알림 일정의 이전 또는 다음 날로 이동할 수 있습니다.
숫자를 읽기 전에 세그먼트를 재계산하여 캐시된 크기를 보지 않도록 하세요. 세그먼트 크기 계산을 참조하세요.

고려해야 할 제한 사항

태그 유형은 영구적입니다. 나중에 유형을 수정하려면 새 태그와 전체 재로드가 필요하므로 첫 업로드 전에 프로필을 계획하세요.
상대 날짜 연산자는 고속 전송 세그먼트에서 사용할 수 없습니다. 고속 전송으로 구성된 애플리케이션은 세그먼트를 미리 컴파일하며, 상대 날짜 연산자는 제공되지 않습니다. 번들 만료 알림은 일반 세그먼트로 실행해야 합니다.
배치 작업은 실시간이 아닙니다. 세그먼트는 마지막으로 성공적으로 로드된 시점의 프로필을 봅니다. 잔액 변경 후 몇 초 내에 실행되어야 하는 시나리오는 야간 배치가 아닌 이벤트 트리거 여정에 속합니다.