메인 콘텐츠로 건너뛰기

​
개요

이 가이드는 OneSignal로 사용자 데이터를 가져오는 다양한 방법을 안내합니다. 다른 플랫폼에서 마이그레이션하든 새 구독자를 추가하든 다음을 사용하여 사용자 및 구독을 가져오거나 업데이트할 수 있습니다:
  • SDK — 새 사용자 및 푸시 구독을 자동으로 추가하는 데 권장됩니다.
  • CSV 가져오기 — 대량 가져오기 및 사용자 업데이트에 가장 적합합니다.
  • REST API — 프로그래밍 방식 또는 자동화된 업데이트에 적합합니다.
  • 수동 입력 — 개별 사용자를 추가하거나 편집하는 데 이상적입니다.

오디언스 섹션 내의 페이지

​
CSV 가져오기

태그, 언어, 시간대, 국가, 구독 상태(이메일/SMS) 및 차단 상태(이메일만)와 함께 이메일 및 전화번호 구독을 가져오거나 업데이트합니다.

CSV 가져오기 화면

​
CSV 준비

파일이 다음 표준을 충족하는지 확인하세요:
  • UTF-8 인코딩 (BOM 제외)
  • 인쇄할 수 없는 문자 없음
  • 깔끔하고 고유한 열 헤더
  • 150MB 미만의 파일 크기
VS Code 또는 Sublime과 같은 일반 텍스트 편집기에서 파일을 엽니다. UTF-8 인코딩으로 다시 열고 적절한 문자 표시를 확인하세요.
파일에는 다음 중 하나 이상이 포함되어야 합니다:
  • external_id — 권장. 모든 구독에서 사용자를 식별합니다.
  • email — 이메일 구독에 필요합니다.
  • phone_number — SMS 구독에 필요합니다.
  • subscription_id — 기존 구독에 외부 ID를 추가할 때만 사용하는 것이 좋습니다.
subscription_id는 레거시 경우 또는 백엔드가 이 고유한 구독 ID를 추적하는 경우 식별자로 사용할 수 있습니다. 속성을 추가하거나 업데이트하는 식별자로 사용하는 것은 권장되지 않습니다.
각 유형의 식별자는 행당 하나만 허용됩니다. 동일한 사용자와 여러 이메일 또는 번호를 연결하려면 동일한 external_id를 공유하는 별도의 행을 사용하세요.
  • external_id를 포함하면 사용자 중복 제거, 채널 간 업데이트 지원 및 향후 가져오기가 가능합니다.
  • external_id가 각 사용자에 대해 고유하고 SDK login 메서드를 통해 설정된 것과 동일한 ID인지 확인하세요. 그렇지 않으면 사용자가 앱을 열 때 재설정됩니다.

​
사용 가능한 CSV 열

​
external_id
고유한 영숫자 값
자세한 내용은 외부 ID를 참조하세요.
​
email
유효한 이메일 주소
이메일 구독을 생성합니다. 이미 존재하는 경우 중복 제거됩니다.
​
phone_number
유효한 전화번호
+15555551234와 같은 E.164 형식을 사용합니다. SMS 구독을 생성합니다.
​
subscription_id
OneSignal에서 할당한 UUID v4
레거시 용도로만 사용됩니다. OneSignal 구독 ID를 추적할 때 사용합니다.
​
subscribed
`yes`, `no`
email, phone_number 및 subscription_id에 대한 구독 상태를 설정합니다.
​
suppressed
`true`, `false`
false는 차단 목록에서 이메일을 제거합니다.
​
timezone_id
IANA TZ 형식의 시간대
IANA TZ를 참조하세요.
​
country
2자 ISO 3166-2 코드
ISO 3166-2를 참조하세요.
​
language
2자 ISO 639-1 코드
ISO 639-1을 참조하세요.
​
data tags
영숫자 값
최대 1,000개의 태그. 열 헤더를 키로 사용합니다. 태그를 참조하세요.

​
단일 열에서 태그 가져오기

각 태그 키에 대해 별도의 열 헤더를 사용하는 대신 단일 tags 헤더를 설정할 수 있으며, 각 사용자 행에는 따옴표 안에 모든 키-값 쌍의 JSON 맵이 포함됩니다. 이는 이전에 태그가 포함된 CSV를 내보내고 다시 포맷하지 않고 다시 가져오려는 경우 특히 유용합니다. 예제 헤더: 
external_id,email,tags
예제 행: 태그는 따옴표로 묶인 JSON 객체로 포맷되어야 합니다. 
userA,example@email.com,"{""level"":""30"",""Color"":""teal""}"
가져오면 OneSignal은 각 키-값 쌍을 구독 레코드의 고유한 태그로 자동 변환합니다.

​
가져오기 전에 AI를 사용하여 CSV 확인

CSV 형식에 오류나 질문이 있는 경우 AI 도구(Claude, ChatGPT 등)에 CSV 문제를 설명하여 다시 가져오기 전에 파일을 자동으로 정리하거나 재구성할 수 있습니다.
  • 태그 삭제
  • 태그 형식
  • 유효하지 않은 형식 식별
  • 전화번호 형식
  • 다른 플랫폼의 데이터
원하지 않는 태그를 삭제하기 위한 AI 프롬프트 예제
이 CSV에서 "user_name"을 제외한 모든 태그를 제거하고 싶습니다.

다음을 수행해 주세요:
1. "user_name" 태그 열만 유지하세요.
2. 다른 모든 태그 열을 제거하세요.
3. 이 문서의 OneSignal 가져오기 요구 사항과 일치하도록 CSV를 형식화하세요:
   https://documentation.onesignal.com/docs/en/import

제 CSV입니다:
[CSV 붙여넣기]
수천 개의 레코드를 가져오기 전에 항상 작은 샘플(5-10행)로 테스트하세요.

​
CSV 가져오기 도구 액세스

  1. 오디언스 > 가져오기로 이동
  2. CSV 가져오기 도구 시작을 클릭
  3. CSV를 업로드합니다(드래그 앤 드롭 또는 파일 선택기 사용)

​
필드 매핑

업로드 후:
  • OneSignal은 헤더를 알려진 속성에 자동으로 매핑합니다.
  • 확인하기 전에 매핑을 검토합니다.

​
속성 업데이트

external_id, email, phone_number 또는 subscription_id를 사용하여 업데이트하려는 사용자를 식별합니다. 기존 사용자에게 새 이메일 또는 전화번호를 추가하려면 external_id를 반드시 사용해야 합니다. subscription_id를 사용하지 마세요 — 구독을 연결하거나 병합하지 않습니다.

​
경고 처리

OneSignal이 형식 문제를 감지하면:
  • CSV를 수정하고 다시 업로드합니다(권장)
  • 또는 영향을 받는 열을 선택 해제하여 가져오기를 건너뜁니다

​
검토

검토 화면에서:
  • 선택적으로 이 가져오기에 대한 세그먼트를 생성합니다
  • 선택적으로 빈 값이 있는 태그를 삭제합니다:
external_id,tag1,tag2
2349-wefh-h34a,,"tag 2 value"
세그먼트를 생성하면 이러한 사용자에게 즉시 메시지를 빠르고 쉽게 보낼 수 있습니다. 그러나 CSV에 이미 고유한 태그가 포함되어 있는 경우 여기에서 세그먼트를 생성할 필요가 없습니다. 이미 설정한 태그를 사용하여 세그먼트를 생성하면 됩니다.

세그먼트를 생성하고 빈 태그 값을 삭제하는 옵션

확인 및 가져오기를 클릭한 후 상태 화면에 진행 상황이 표시됩니다. 가져오기가 완료되면 이메일을 받게 됩니다.
가져오기 기간은 파일 크기에 따라 다릅니다. 완료 이메일을 받으려면 이메일 연락처에 contact@onesignal.com을 추가하세요.

​
이메일 확인 및 문제 해결

CSV 업로드가 완료되면 다음 데이터가 포함된 확인 이메일을 받게 됩니다:
  • 추가된 구독 레코드
    • CSV 업로드를 통해 생성된 새 이메일 및/또는 SMS 구독 수입니다.
    • 0은 목록에 구독을 생성하기 위한 고유한 email 및/또는 phone_number 식별자가 포함되지 않았음을 의미합니다.
  • 수정된 구독 레코드
    • 태그 설정 또는 기타 속성과 같이 일부 데이터가 변경된 구독 수입니다.
    • 사용자는 여러 구독을 가질 수 있다는 점을 기억하세요. 예를 들어, 10개의 외부 ID 목록을 업로드하고 각각이 20개의 구독과 연결된 경우 200개의 구독 레코드가 수정된 것으로 표시됩니다.
  • 건너뛴 구독 업데이트
    • 제공된 이유로 건너뛴 구독 수입니다.
    • email 및/또는 phone_number의 CSV를 업로드한 경우 해당 구독이 생성되었을 가능성이 높습니다.
    • 이유가 “앱의 태그 제한을 초과하여”인 경우 태그를 제거하고 다시 업로드해야 합니다. 또는 플랜을 업그레이드하세요.
  • 가져오지 않음
    • 업데이트되거나 가져오지 않은 행 수입니다.
    • 일반적으로 다음과 같은 경우에 발생합니다:
    1. CSV에 설정한 external_id가 OneSignal 앱의 구독에 존재하지 않습니다
    2. email 및/또는 phone_number 구독이 이미 OneSignal 앱에 존재합니다.
  • 생성된 새 세그먼트
    • 해당하는 경우 생성한 세그먼트의 이름입니다.

이메일 확인 예제.

예제에서:
  • email 및/또는 phone_number 열에 OneSignal 앱에 현재 존재하지 않는 고유한 이메일 주소 및/또는 전화번호가 포함되어 있어 100개의 구독이 생성되었습니다.
  • 37814개의 구독이 업데이트되었습니다. 이것은 사용자의 수가 아닙니다. 사용자는 여러 구독을 가질 수 있다는 점을 기억하세요.
  • CSV의 621852개 행이 가져오지 않았습니다. OneSignal 앱의 사용자에게 매핑되는 외부 ID가 없거나 이메일 및/또는 전화번호가 고유한 데이터 설정 없이 이미 존재했기 때문입니다.
현재 세그먼트는 구독된 구독의 수만 계산합니다. 데이터가 업데이트되었지만 구독 취소된 구독은 계산하지 않습니다.세그먼트 수가 CSV와 일치하지 않는 경우 세그먼트가 현재 구독 취소된 구독을 계산하지 않기 때문입니다.이 기능은 현재 작업 중입니다. 새롭고 개선된 세그먼테이션은 2025년 후반에 제공될 예정입니다.
여전히 문제가 있습니까?support@onesignal.com에 문의하여 업로드한 CSV 파일과 확인 이메일의 스크린샷을 공유하세요. 기꺼이 살펴보겠습니다!

​
일반적인 문제 해결 팁

다음은 CSV 가져오기에서 흔히 발생하는 문제입니다. 문제가 있는 경우 위의 가져오기 전에 AI를 사용하여 CSV 확인 섹션을 시도하는 것도 권장합니다.

​
태그 제한

  • 태그 플랜 제한은 사용자별입니다. 앱당 무제한 수의 태그를 가질 수 있지만 각 사용자는 플랜 제한의 적용을 받습니다.
  • 예: 플랜 제한은 사용자당 20개의 태그입니다.
    • 사용자가 이미 19개의 태그를 가지고 있는 경우 해당 사용자에게 1개의 태그만 더 추가할 수 있습니다.
    • 앱에는 1000개의 다른 태그 조합이 있을 수 있지만 각 사용자는 한 번에 20개만 가질 수 있습니다.
  • 권장 사항:
    • 대시보드 CSV 내보내기를 사용하여 사용자의 외부 ID, 태그, 이메일 및/또는 전화번호를 내보냅니다.
    • 삭제하려는 태그로 CSV 헤더를 설정하고 먼저 가져옵니다.
    • 유지하려는 태그로 두 번째 CSV를 설정하고 두 번째로 가져옵니다.
    • 자세한 내용은 위의 단일 열에서 태그 가져오기 섹션을 참조하세요.

​
태그 덮어쓰기 및 삭제

CSV 가져오기 중:
  • CSV에 포함된 태그는 제공된 값으로 덮어씁니다.
  • CSV에 포함되지 않은 태그는 사용자 레코드에서 변경되지 않습니다.
가져오기 후에도 태그가 여전히 존재하는 경우 다음을 확인하세요:
  • 헤더 열에 태그 키가 포함되어 있습니다.
  • 행에 값이 포함되어 있지 않습니다.
  • 검토 화면에서 “빈 값이 있는 태그 삭제” 옵션을 선택했습니다.

​
태그가 추가되는 다른 소스

삭제된 태그가 가져오기 후 다시 나타나면 통합이 자동으로 다시 작성하고 있을 수 있습니다. 일반적인 소스는 다음과 같습니다:
  • Segment
  • HubSpot
  • Journeys
  • SDK 태깅 메서드
  • 사용자 지정 API 또는 ETL 파이프라인
통합 매핑 및 이벤트 트리거를 검토하여 CSV 변경 사항을 덮어쓰지 않는지 확인하세요.
도움이 필요하십니까?

​
수동 입력

OneSignal 대시보드를 통해 오디언스 > 사용자 > 사용자 업데이트/가져오기 > 수동으로 사용자 추가로 이동하여 사용자의 이메일 및 전화번호 구독을 수동으로 추가할 수 있습니다.

수동으로 사용자 추가 화면

새 사용자 화면에서 원하는 데이터를 포함하고 사용자 생성을 선택합니다.