애플리케이션 개발자를 위한 푸시 알림 디바이스 등록

Customer Insights - Journeys에서 푸시 알림을 설정하는 전반적인 접근 방식에 대해 자세히 알아보려면 푸시 알림 설정 개요를 방문하십시오.

Customer Insights - Journeys에서 푸시 알림을 활성화하려면 다음 단계를 완료해야 합니다.

이 다이어그램에서는 Customer Insights - Journeys 내에서 디바이스 및 사용자를 등록하는 데 필요한 두 단계를 설명합니다.

푸시 알림 디바이스 및 사용자 등록 다이어그램.

디바이스 등록

모바일 앱 구성을 완료하려면 개발자가 여러 서버에 디바이스를 등록해야 합니다. 이미 Customer Insights - Journeys에서 디바이스 토큰, 사용자 ID(연락처 ID, 잠재 고객 ID, 데이터 프로필 ID) 및 모바일 애플리케이션 ID를 확보해야 합니다.

디바이스 등록 요청이 성공적으로 호출되면 202 응답이 표시됩니다. 202 응답은 요청이 수락되었음을 나타냅니다. 성공적인 요청을 확인하려면 웹후크를 사용하거나 상태 엔드포인트를 직접 호출하여 상태를 확인해야 합니다.

API

디바이스 등록(단일)

샘플 HTTP 요청(iOS):

POST {PublicEndpoint}/api/v1.0/orgs/%ORG_ID%/pushdeviceregistration/devices

{
    "MobileAppId": "00000000-0000-0000-0000-000000000000",
    "UserId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "ApiToken": "%API_TOKEN%",
    "ApnsDeviceToken": "%APNS_TOKEN%"
}

샘플 HTTP 요청(Android):

POST {PublicEndpoint}/api/v1.0/orgs/%ORG_ID%/pushdeviceregistration/devices

{
    "MobileAppId": "00000000-0000-0000-0000-000000000000",
    "UserId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "ApiToken": "%API_TOKEN%",
    "FcmDeviceToken": "%FCM_TOKEN%"
}

헤더:

x-ms-track-registration: true이면 등록 성공/실패에 대한 정보가 저장되고 등록 상태 API를 통해 사용할 수 있습니다.
x-ms-callback-url: 비어 있지 않으면 실패하거나 성공한 디바이스 등록이 POST 요청 웹후크를 트리거합니다.
x-ms-callback-url-headers: 웹후크 요청에 대해 전달된 헤더를 나타내는 문자열-문자열 사전의 직렬화된 JSON을 포함합니다. x-ms-callback-url이 정의된 경우에만 사용됩니다.

반환: 제공된 요청이 유효한 경우 202이고, 그렇지 않으면 400입니다.

응답 본문:

x-ms-track-registration이 true인 경우:

{
    "RegistrationRequestId": "%GUID%"
}

그렇지 않으면 본문이 비어 있습니다.

정의

이름	Description
MobileAppId	Customer Insights - Journeys에 구성된 모바일 애플리케이션의 식별자입니다.
UserId	Customer Insights - Journeys에서 연락처, 잠재 고객 또는 Customer Insights - Data 프로필의 사용자 식별자입니다.
ApiToken	요청에 권한을 부여하는 API 토큰입니다.
ApnsDeviceToken	iOS 애플리케이션에서 생성된 고유한 디바이스 토큰 식별자입니다. iOS 디바이스에 대해서만 전송됩니다.
FcmDeviceToken (FCM 디바이스 토큰)	Android 애플리케이션에서 생성된 고유한 디바이스 토큰 식별자입니다. Android 디바이스에 대해서만 전송됩니다.

디바이스 등록(다중)

일괄 등록 본문에는 디바이스 등록 요청을 나타내는 최대 100개의 개체 배열이 포함됩니다.

샘플 HTTP 요청(iOS):

POST {PublicEndpoint}/api/v1.0/orgs/%ORG_ID%/pushdeviceregistration/devices/batch

[
    {
        "MobileAppId": "00000000-0000-0000-0000-000000000000",      
        "UserId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
        "ApiToken": "%API_TOKEN%",
        "ApnsDeviceToken": "%APNS_TOKEN%"
    },
    {
        "MobileAppId": "00000000-0000-0000-0000-000000000000",
        "UserId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
        "ApiToken": "%API_TOKEN%",
        "ApnsDeviceToken": "%APNS_TOKEN%"
    }
]

샘플 HTTP 요청(Android):

POST {PublicEndpoint}/api/v1.0/orgs/%ORG_ID%/pushdeviceregistration/devices/batch

[
    {
        "MobileAppId": "00000000-0000-0000-0000-000000000000",      
        "UserId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
        "ApiToken": "%API_TOKEN%",
        "FcmDeviceToken": "%FCM_TOKEN%"
    },
    {
        "MobileAppId": "00000000-0000-0000-0000-000000000000",
        "UserId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
        "ApiToken": "%API_TOKEN%",
        "FcmDeviceToken": "%FCM_TOKEN%"
    }
]

헤더:

x-ms-track-registration: true이면 등록 성공 또는 실패에 대한 정보가 저장되고 등록 상태 API를 통해 사용할 수 있습니다.
x-ms-callback-url: 비어 있지 않으면 디바이스 등록에 실패하거나 성공하면 POST 요청 웹후크가 트리거됩니다.
x-ms-callback-url-headers: 웹후크 요청에 대해 전달된 헤더를 나타내는 문자열-문자열 사전의 직렬화된 JSON을 포함합니다. 정의된 경우에만 x-ms-callback-url 사용됩니다.

반환: 제공된 요청이 유효한 경우 202이고, 그렇지 않으면 400입니다.

응답 본문:

x-ms-track-registration이 true인 경우 항목 배열은 각 항목 순서가 요청 본문 배열의 순서에 해당합니다.

[
    {
        "RegistrationRequestId": "%REG_REQUEST_ID%"
    },
    {
        "RegistrationRequestId": "%REG_REQUEST_ID%"
    }
]

그렇지 않으면 본문이 비어 있습니다.

디바이스 등록 상태

POST  {PublicEndpoint}/api/v1.0/orgs/%ORG_ID%/pushdeviceregistration/devices/status/

요청 본문:

{
    "RegistrationRequestIds": [
        "%REG_REQUEST_ID%"
    ],
    "MobileAppId": "%MOBILE_APP_ID%",
    "ApiToken": "%API_TOKEN%"
}

반환: 제공된 요청이 유효한 경우 200이고, 그렇지 않으면 400입니다.

응답 본문 - 항목 배열:

[
    {
        "Status": "Pending|Success|Failed",
        "FailureReason": " DuplicateExists|DryRunSendingFailed|DeviceTokenTooLong|FailedToStoreDevice|ApiTokenNotValid " // dry run sending is a verification of device token by sending an invisible notification to mobile app. Such sending failure might happen due to a wrong device token or incorrect/expired mobile app auth data
    },
    {
        "Status": "Pending|Success|Failed",
        "FailureReason": " DuplicateExists|DryRunSendingFailed|DeviceTokenTooLong|FailedToStoreDevice|ApiTokenNotValid " // dry run sending is a verification of device token by sending an invisible notification to mobile app. Such sending failure might happen due to a wrong device token or incorrect/expired mobile app auth data
    }
]

각 항목 순서는 RegistrationRequestIds 배열의 순서에 해당합니다.

정의

이름	Description
등록 요청 식별자	개별 등록 요청의 배열입니다. 값은 등록 호출의 응답에서 가져옵니다. x-ms-track-registration 헤더가 등록에 사용된 경우에만 제공됩니다.
MobileAppId	Customer Insights - Journeys에 구성된 모바일 애플리케이션의 식별자입니다.
UserId	Customer Insights - Journeys에서 연락처, 잠재 고객 또는 Customer Insights - Data 프로필의 사용자 식별자입니다.

중요합니다

상태가 "보류 중" 상태로 중단될 수 있는 세 가지 가능한 이유가 있습니다.

원래 디바이스 등록 요청에 잘못된 API 토큰이 있었습니다. 악의적인 행위자가 "레지스터 디바이스"를 호출하고 무한 제한을 생성하여 환경에 대해 DoS 공격을 수행하지 못하도록 하기 위해 이러한 시도는 등록 기록 저장을 생성하지 않습니다. 따라서 성공을 확인할 정보가 없습니다.
CRM은 여러 시간 동안 제한된 상태로 유지되어 상태 업데이트 작업이 여러 번의 재시도 후 해당 작업을 실행하지 못합니다.
제공된 x-ms-track-registration 헤더 없이 디바이스 등록 요청이 이루어졌습니다.

디바이스 등록 상태 웹후크

디바이스 등록이 성공하거나 실패할 때 x-ms-status-callback-url 이 URL을 제공하는 경우 Customer Insights - Journeys는 헤더 값에 액세스합니다.

디바이스 등록 요청의 x-ms-status-callback-url 헤더 내에 제공된 URL에 게시합니다.

본문:

{ 
    "Status": "Success|Failed", 
    "Signature": "%SIGNATURE%", 
    "FailureReason": " DuplicateExists|DryRunSendingFailed|DeviceTokenTooLong|FailedToStoreDevice|ApiTokenNotValid" 
}

팁 (조언)

서명은 API 토큰을 키로 사용하여 계산된 콜백 URL의 HMACSHA256 해시입니다. 이 값을 사용하여 Customer Insights - Journeys가 호출했는지 확인합니다. 동일한 알고리즘을 사용하고 값을 비교하여 웹후크 쪽에서 API 토큰으로 콜백 URL을 해시합니다.

비고

요청을 한 번 시도합니다. 요청을 실행하지 못하면 알림이 손실됩니다. 오류 유형에는 잘못된 콜백 URL, REST API 호출 시간 제한 또는 예기치 않은 응답 상태 코드가 포함됩니다.

반환: 제공된 요청이 유효한 경우 202이고, 그렇지 않으면 400입니다.

예상 본문: 빈 본문입니다.

디바이스 정리(단일)

데이터베이스에서 더 이상 유효하지 않은 디바이스를 제거하여 성능이 좋은 메시지 전송을 보장하는 것이 중요합니다. 다음 방법을 사용하여 디바이스 테이블에서 이전 디바이스, 사용자 및 애플리케이션 조합을 제거합니다.

POST {PublicEndpoint}/api/v1.0/orgs/%ORG_ID%/pushdeviceregistration/devices/cleanup

{
    "MobileAppId": "00000000-0000-0000-0000-000000000000",
    "ApiToken": "%API_TOKEN%",
    "UserId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "DeviceToken": "%OPTIONAL_FCM_OR_APNS_DEVICE_TOKEN%"
}

반환: 제공된 요청이 유효한 경우 202이고, 그렇지 않으면 400입니다.

정의

이름	Description
MobileAppId	Customer Insights - Journeys에 구성된 모바일 애플리케이션의 식별자입니다.
ApiToken	요청에 권한을 부여하는 API 토큰입니다.
UserId	Customer Insights - Journeys에서 연락처, 잠재 고객 또는 Customer Insights - Data 프로필의 사용자 식별자입니다.
디바이스토큰	애플리케이션에서 생성한 고유한 디바이스 토큰 식별자입니다.

디바이스 정리(다중)

POST {PublicEndpoint}/api/v1.0/orgs/%ORG_ID%/pushdeviceregistration/devices/cleanup/batch

{
    "MobileAppId": "00000000-0000-0000-0000-000000000000",
    "ApiToken": "%API_TOKEN%",
    "UserId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "DeviceToken": "%OPTIONAL_FCM_OR_APNS_DEVICE_TOKEN%"
}

반환: 제공된 요청이 유효한 경우 202이고, 그렇지 않으면 400입니다.

정의

이름	Description
MobileAppId	Customer Insights - Journeys에 구성된 모바일 애플리케이션의 식별자입니다.
ApiToken	요청에 권한을 부여하는 API 토큰입니다.
UserId	Customer Insights - Journeys에서 연락처, 잠재 고객 또는 Customer Insights - Data 프로필의 사용자 식별자입니다.
디바이스토큰	애플리케이션에서 생성한 고유한 디바이스 토큰 식별자입니다.

Last updated on 2025-09-22

다음을 통해 공유

애플리케이션 개발자를 위한 푸시 알림 디바이스 등록

디바이스 등록

API

디바이스 등록(단일)

정의

디바이스 등록(다중)

디바이스 등록 상태

정의

디바이스 등록 상태 웹후크

디바이스 정리(단일)

정의

디바이스 정리(다중)

정의

추가 리소스