기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다. # 모바일 푸시 알림에 Amazon SNS 사용 이 섹션에서는 모바일 푸시 알림을 보내는 방법을 설명합니다. ## 주제에 게시 Amazon SNS를 사용하여 주제를 구독하는 모바일 엔드포인트에 메시지를 전송할 수도 있습니다. [Amazon SNS란 무엇인가요?](welcome.md)에 설명된 대로 Amazon SQS, HTTP/S, 이메일, SMS 등 다른 엔드포인트 유형에서 주제를 구독하는 것과 동일한 개념입니다. 차이점은 Amazon SNS가 Apple 푸시 알림 서비스(APNS) 및 Google Firebase Cloud Messaging(FCM)과 같은 알림 서비스를 통해 통신한다는 것입니다. 알림 서비스를 통해 구독된 모바일 엔드포인트는 주제로 전송된 알림을 수신합니다. ## Direct Amazon SNS 모바일 디바이스 메시징 모바일 디바이스에서 애플리케이션을 나타내는 엔드포인트에 Amazon SNS 푸시 알림 메시지를 직접 전송할 수 있습니다. **직접 메시지를 전송하려면** 1. [Amazon SNS 콘솔](https://console.aws.amazon.com/sns/home)에 로그인합니다. 1. 탐색 창에서 **Push notifications**(푸시 알림)를 선택합니다. 1. **Mobile push notifications**(모바일 푸시 알림) 페이지의 **Platform applications**(플랫폼 애플리케이션) 섹션에서 ***MyApp***과 같은 애플리케이션 이름을 선택합니다. 1. ***MyApp*** 페이지의 **엔드포인트(Endpoints)** 섹션에서 엔드포인트를 선택한 후 **메시지 게시(Publish message)**를 선택합니다. 1. **엔드포인트에 메시지 게시(Publish message to endpoint)** 페이지에서, 모바일 디바이스에서 애플리케이션에 나타나는 메시지를 입력한 후 **메시지 게시(Publish message)**를 선택합니다. Amazon SNS는 알림 메시지를 플랫폼 알림 서비스로 전송하고, 해당 메시지가 애플리케이션에 전송되게 합니다. # 플랫폼별 페이로드를 사용하여 Amazon SNS 알림 게시 AWS Management Console 또는 Amazon SNS APIs를 사용하여 플랫폼별 페이로드가 포함된 사용자 지정 메시지를 모바일 디바이스로 전송할 수 있습니다. Amazon SNS API 사용에 대한 자세한 내용은 [모바일 푸시 API 작업](mobile-push-api.md) 및 `[snsmobilepush.zip](samples/snsmobilepush.zip)`의 `SNSMobilePush.java` 파일을 참조하세요. ## JSON 형식 메시지 전송 중 플랫폼별 페이로드를 전송할 때 데이터는 JSON 키-값 쌍 문자열 형식이어야 하며, 따옴표가 이스케이프되어 있어야 합니다. 다음 예제는 FCM 플랫폼에 대한 사용자 지정 메시지를 보여줍니다. ``` { "GCM": "{\"fcmV1Message\": {\"message\": {\"notification\": {\"title\": \"Hello\", \"body\": \"This is a test.\"}, \"data\": {\"dataKey\": \"example\"}}}}" } ``` ## 플랫폼별 메시지 전송 중 사용자 지정 데이터를 키-값 쌍으로 전송할 수 있을 뿐 아니라, 플랫폼별 키-값 쌍을 전송할 수도 있습니다. FCM `data` 파라미터에서 사용자 지정 데이터 키-값 쌍 뒤에 FCM 파라미터 `time_to_live` 및 `collapse_key`가 포함되어 있음을 보여줍니다. ``` { "GCM": "{\"fcmV1Message\": {\"message\": {\"notification\": {\"title\": \"TitleTest\", \"body\": \"Sample message for Android or iOS endpoints.\"}, \"data\":{\"time_to_live\": 3600,\"collapse_key\":\"deals\"}}}}" } ``` Amazon SNS에서 지원하는 각 푸시 알림 서비스에서 지원되는 키-값 쌍 목록은 다음을 참조하세요. **중요** Amazon SNS는 이제 Android 디바이스로 모바일 푸시 알림을 보내기 위해 Firebase Cloud Messaging(FCM) HTTP v1 API를 지원합니다. 2024년 3월 26일 - Amazon SNS는 Apple 디바이스 및 Webpush 대상에 대한 FCM HTTP v1 API를 지원합니다. 애플리케이션 중단을 방지하려면 2024년 6월 1일 또는 그 이전에 기존 모바일 푸시 애플리케이션을 최신 FCM HTTP v1 API로 마이그레이션하는 것이 좋습니다. + APNS 설명서의 [페이로드 키 참조](https://developer.apple.com/library/archive/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/PayloadKeyReference.html#/apple_ref/doc/uid/TP40008194-CH17-SW1) + FCM 설명서의 [Firebase Cloud Messaging HTTP 프로토콜](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages) + ADM 설명서의 [메시지 보내기](https://developer.amazon.com/sdk/adm/sending-message.html) ## 다중 플랫폼의 애플리케이션으로 메시지 전송 중 FCM 및 APNS와 같은 다중 플랫폼용 디바이스에 설치된 애플리케이션에 메시지를 전송하려면 먼저 모바일 엔드포인트에서 Amazon SNS의 주제를 구독한 다음 메시지를 주제에 게시해야 합니다. 다음 예제에서는 APNS, FCM 및 ADM에서 구독 중인 모바일 엔드포인트에 전송할 메시지를 보여 줍니다. ``` { "default": "This is the default message which must be present when publishing a message to a topic. The default message will only be used if a message is not present for one of the notification platforms.", "APNS": "{\"aps\":{\"alert\": \"Check out these awesome deals!\",\"url\":\"www.amazon.com\"} }", "GCM": "{\"data\":{\"message\":\"Check out these awesome deals!\",\"url\":\"www.amazon.com\"}}", "ADM": "{\"data\":{\"message\":\"Check out these awesome deals!\",\"url\":\"www.amazon.com\"}}" } ``` ## 경보 또는 백그라운드 알림으로서 메시지를 APNS로 전송 Amazon SNS는 `alert` 또는 `background` 알림으로 APNS에 메시지를 보낼 수 있습니다(자세한 내용은 APNS 설명서의 [앱에 백그라운드 업데이트 푸시](https://developer.apple.com/documentation/usernotifications/setting_up_a_remote_notification_server/pushing_background_updates_to_your_app) 참조). + `alert` APNS 알림은 경보 메시지를 표시하거나 사운드를 재생하거나 애플리케이션 아이콘에 배지를 추가하여 사용자에게 알립니다. + `background` APNS 알림은 사용자에게 알리지 않고 알림의 내용을 실행하도록 애플리케이션을 가동하거나 명령합니다. ### 사용자 지정 APNS 헤더 값 지정 Amazon SNS `Publish` API 작업, AWS SDKs 또는를 사용하여 `AWS.SNS.MOBILE.APNS.PUSH_TYPE` [예약된 메시지 속성](sns-message-attributes.md#sns-attrib-mobile-reserved)에 대한 사용자 지정 값을 지정하는 것이 좋습니다 AWS CLI. 다음 CLI 예제는 지정된 주제에 `content-available`을 `1`로 설정하고 `apns-push-type`을 `background`로 설정합니다. ``` aws sns publish \ --endpoint-url https://sns.us-east-1.amazonaws.com \ --target-arn arn:aws:sns:us-east-1:123456789012:endpoint/APNS_PLATFORM/MYAPP/1234a567-bc89-012d-3e45-6fg7h890123i \ --message '{"APNS_PLATFORM":"{\"aps\":{\"content-available\":1}}"}' \ --message-attributes '{ \ "AWS.SNS.MOBILE.APNS.TOPIC":{"DataType":"String","StringValue":"com.amazon.mobile.messaging.myapp"}, \ "AWS.SNS.MOBILE.APNS.PUSH_TYPE":{"DataType":"String","StringValue":"background"}, \ "AWS.SNS.MOBILE.APNS.PRIORITY":{"DataType":"String","StringValue":"5"}}' \ --message-structure json ``` **참고** JSON 구조가 유효한지 확인합니다. 마지막 키를 제외한 각 키-값 페어 뒤에 쉼표를 추가합니다. ### 페이로드에서 APNS 푸시 유형 헤더 추론 `apns-push-type` APNS 헤더를 설정하지 않으면 Amazon SNS에서 JSON 형식 APNS 페이로드 구성의 `aps` 사전에 있는 `content-available` 키에 따라 헤더를 `alert` 또는 `background`로 설정합니다. **참고** Amazon SNS는 `alert` 또는 `background` 헤더만 유추할 수 있지만 `apns-push-type` 헤더는 다른 값으로 설정할 수 있습니다. + 다음의 경우 `apns-push-type`이 `alert`로 설정됩니다. + `aps` 사전에 `1`로 설정된 `content-available`과 사용자 상호 작용을 트리거하는 *하나 이상의 키*가 포함되어 있는 경우. + `aps` 사전에 `0`으로 설정된 `content-available`이 포함되어 있거나 *또는* `content-available` 키가 없는 경우. + `content-available` 키의 값이 정수 또는 부울이 아닌 경우. + 다음의 경우 `apns-push-type`이 `background`로 설정됩니다. + `aps` 사전에 `1`로 설정된 `content-available`*만* 포함되어 있고 사용자 상호 작용을 트리거하는 *다른 키가 없는* 경우입니다. **중요** Amazon SNS에서 APNS에 대한 원시 구성 객체를 백그라운드 전용 알림으로 전송하는 경우, `1`로 설정된 `content-available`을 `aps` 사전에 포함해야 합니다. 사용자 지정 키를 포함할 수 있지만 `aps` 사전에는 사용자 상호 작용을 트리거하는 키(예: 경보, 배지 또는 사운드)를 포함할 수 없습니다. 다음은 원시 구성 객체의 예입니다. ``` { "APNS": "{\"aps\":{\"content-available\":1},\"Foo1\":\"Bar\",\"Foo2\":123}" } ``` 이 예에서 Amazon SNS는 메시지에 대한 `apns-push-type` APNS 헤더를 `background`로 설정합니다. Amazon SNS는 `apn` 사전에 `1`로 설정된 `content-available` 키가 포함되어 있고 사용자 상호 작용을 트리거할 수 있는 다른 키가 포함되어 있지 않음을 감지하면 헤더를 `background`로 설정합니다. # Amazon SNS에서 Google Firebase Cloud Messaging v1 페이로드 사용 Amazon SNS는 FCM HTTP v1 API를 사용하여 Android, iOS 및 Webpush 대상으로 알림을 보낼 수 있도록 지원합니다. 이 주제에서는 CLI 또는 Amazon SNS API를 사용하여 모바일 푸시 알림을 게시할 때 페이로드 구조의 예를 제공합니다. FCM 알림을 보낼 때 페이로드에 다음 메시지 유형을 포함할 수 있습니다. + **데이터 메시지** - 데이터 메시지는 클라이언트 앱에서 처리되며 사용자 지정 키-값 페어를 포함합니다. 데이터 메시지를 구성할 때 JSON 객체가 있는 `data` 키를 값으로 포함시킨 다음 사용자 지정 키-값 페어를 입력해야 합니다. + **알림 메시지** 또는 **표시 메시지** - 알림 메시지에는 FCM SDK에서 처리하는 미리 정의된 키 세트가 포함되어 있습니다. 이러한 키는 전송하려는 디바이스 유형에 따라 다릅니다. 플랫폼별 알림 키에 대한 자세한 내용은 다음을 참조하세요. + [Android 알림 키](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages) + [APNS 알림 키](https://developer.apple.com/documentation/usernotifications/generating-a-remote-notification) + [Webpush 알림 키](https://developer.mozilla.org/en-US/docs/Web/API/Notification) FCM 메시지 유형에 대한 자세한 내용은 Google *Firebase* 설명서의 에서 [메시지 유형](https://firebase.google.com/docs/cloud-messaging/concept-options#notifications_and_data_messages)을 참조하세요. ## FCM v1 페이로드 구조를 사용하여 메시지 전송 FCM 애플리케이션을 처음 생성하거나 FCM v1 기능을 활용하려는 경우 FCM v1 형식의 페이로드를 전송하도록 선택할 수 있습니다. 이렇게 하려면 최상위 키 `fcmV1Message`를 포함해야 합니다. FCM v1 페이로드 구성에 대한 자세한 내용은 Google *Firebase* 설명서의 [레거시 FCM APIs에서 HTTP v1로 마이그레이션](https://firebase.google.com/docs/cloud-messaging/migrate-v1) 및 [플랫폼 간에 메시지 사용자 지정](https://firebase.google.com/docs/cloud-messaging/concept-options#customizing-a-message-across-platforms)을 참조하세요. **Amazon SNS페이로드:** **참고** 다음 예제에서 사용되는 `GCM` 키 값은 Amazon SNS 를 사용하여 알림을 게시할 때 문자열로 인코딩되어야 합니다. ``` { "GCM": "{ \"fcmV1Message\": { \"validate_only\": false, \"message\": { \"notification\": { \"title\": \"string\", \"body\": \"string\" }, \"data\": { \"dataGen\": \"priority message\" }, \"android\": { \"priority\": \"high\", \"notification\": { \"body_loc_args\": [\"string\"], \"title_loc_args\": [\"string\"], \"sound\": \"string\", \"title_loc_key\": \"string\", \"title\": \"string\", \"body\": \"string\", \"click_action\": \"clicky_clacky\", \"body_loc_key\": \"string\" }, \"data\": { \"dataAndroid\": \"priority message\" }, \"ttl\": \"10023.32s\" }, \"apns\": { \"payload\": { \"aps\": { \"alert\": { \"subtitle\": \"string\", \"title-loc-args\": [\"string\"], \"title-loc-key\": \"string\", \"loc-args\": [\"string\"], \"loc-key\": \"string\", \"title\": \"string\", \"body\": \"string\" }, \"category\": \"Click\", \"content-available\": 0, \"sound\": \"string\", \"badge\": 5 } } }, \"webpush\": { \"notification\": { \"badge\": \"5\", \"title\": \"string\", \"body\": \"string\" }, \"data\": { \"dataWeb\": \"priority message\" } } } } }" } ``` JSON 페이로드를 전송할 때는 요청에 `message-structure` 속성을 포함시키고 `json`으로 설정해야 합니다. **CLI 예제:** ``` aws sns publish --topic $TOPIC_ARN --message '{"GCM": "{\"fcmV1Message\": {\"message\":{\"notification\":{\"title\":\"string\",\"body\":\"string\"},\"android\":{\"priority\":\"high\",\"notification\":{\"title\":\"string\",\"body\":\"string\"},\"data\":{\"customAndroidDataKey\":\"custom key value\"},\"ttl\":\"0s\"},\"apns\":{\"payload\":{\"aps\":{\"alert\":{\"title\":\"string\", \"body\":\"string\"},\"content-available\":1,\"badge\":5}}},\"webpush\":{\"notification\":{\"badge\":\"URL\",\"body\":\"Test\"},\"data\":{\"customWebpushDataKey\":\"priority message\"}},\"data\":{\"customGeneralDataKey\":\"priority message\"}}}}", "default": "{\"notification\": {\"title\": \"test\"}"}' --region $REGION --message-structure json ``` FCM v1 형식의 페이로드를 보내는 방법에 대한 자세한 내용은 Google의 *Firebase* 설명서에서 다음을 참조하세요. + [레거시 FCM APIs에서 HTTP v1로 마이그레이션](https://firebase.google.com/docs/cloud-messaging/migrate-v1) + [FCM 메시지 정보](https://firebase.google.com/docs/cloud-messaging/concept-options#customizing_a_message_across_platforms) + [REST 리소스: projects.messages](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages) ## 레거시 페이로드 구조를 사용하여 FCM v1 API로 메시지 전송 FCM v1로 마이그레이션할 때 레거시 자격 증명에 사용하던 페이로드 구조를 변경할 필요가 없습니다. Amazon SNS는 페이로드를 새 FCM v1 페이로드 구조로 변환하고 Google로 전송합니다. 입력 메시지 페이로드 형식: ``` { "GCM": "{\"notification\": {\"title\": \"string\", \"body\": \"string\", \"android_channel_id\": \"string\", \"body_loc_args\": [\"string\"], \"body_loc_key\": \"string\", \"click_action\": \"string\", \"color\": \"string\", \"icon\": \"string\", \"sound\": \"string\", \"tag\": \"string\", \"title_loc_args\": [\"string\"], \"title_loc_key\": \"string\"}, \"data\": {\"message\": \"priority message\"}}" } ``` Google로 전송된 메시지: ``` { "message": { "token": "***", "notification": { "title": "string", "body": "string" }, "android": { "priority": "high", "notification": { "body_loc_args": [ "string" ], "title_loc_args": [ "string" ], "color": "string", "sound": "string", "icon": "string", "tag": "string", "title_loc_key": "string", "title": "string", "body": "string", "click_action": "string", "channel_id": "string", "body_loc_key": "string" }, "data": { "message": "priority message" } }, "apns": { "payload": { "aps": { "alert": { "title-loc-args": [ "string" ], "title-loc-key": "string", "loc-args": [ "string" ], "loc-key": "string", "title": "string", "body": "string" }, "category": "string", "sound": "string" } } }, "webpush": { "notification": { "icon": "string", "tag": "string", "body": "string", "title": "string" }, "data": { "message": "priority message" } }, "data": { "message": "priority message" } } } ``` **잠재적 위험** + 레거시 대 v1 매핑은 Apple Push Notification Service(APNS) `headers` 또는 `fcm_options` 키를 지원하지 않습니다. 이러한 필드를 사용하려면 FCM v1 페이로드를 전송합니다. + 경우에 따라 FCM v1에서 메시지 헤더를 사용하여 APNs 디바이스에 자동 알림을 보내야 합니다. 현재 APN 디바이스에 자동 알림을 보내는 경우 레거시 접근 방식에서는 작동하지 않습니다. 대신 예상치 못한 문제를 방지하려면 FCM v1 페이로드를 사용하는 것이 좋습니다. APN 헤더 목록과 헤더의 용도를 찾으려면 *Apple 개발자 안내서*의 [ APNs과의 통신을 참조하세요](https://developer.apple.com/library/archive/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/CommunicatingwithAPNs.html). + 알림을 보낼 때 `TTL` Amazon SNS 속성을 사용하는 경우 `android` 필드에서만 업데이트됩니다. `TTL` APNS 속성을 설정하려면 FCM v1 페이로드를 사용합니다. + `android`, `apns` 및 `webpush` 키는 제공된 모든 관련 키로 매핑되고 채워집니다. 예를 들어 세 플랫폼 모두에서 공유하는 키인 `title`을 제공하는 경우 FCM v1 매핑은 세 플랫폼 모두에 입력한 제목을 채웁니다. + 플랫폼 간에 공유되는 일부 키는 다양한 값 유형을 기대합니다. 예를 들어 에 전달된 `badge` 키는 정수 값을 `apns` 예상하는 반면 `webpush`에 전달된 `badge` 키는 문자열 값을 예상합니다. `badge` 키를 제공하는 경우 FCM v1 매핑은 유효한 값을 제공한 키만 채웁니다. ## FCM 전송 실패 이벤트 다음 표는 FCM v1 알림 요청에 대해 Google에서 수신한 오류/상태 코드에 해당하는 Amazon SNS 실패 유형을 제공합니다. 애플리케이션에 대한 [전송 상태 로깅](topics-attrib.md)을 설정할 때 FCM v1 API에서 수신한 모든 관찰된 오류 코드를 CloudWatch에서 사용할 수 있습니다. | FCM 오류/상태 코드 | Amazon SNS 장애 유형 | 오류 메시지 | 원인 및 완화 | | --- | --- | --- | --- | | `UNREGISTERED` | `InvalidPlatformToken` | 엔드포인트와 연결된 플랫폼 토큰이 유효하지 않습니다. | 엔드포인트에 연결된 디바이스 토큰이 오래되었거나 유효하지 않습니다. Amazon SNS가 엔드포인트를 비활성화했습니다. Amazon SNS 엔드포인트를 최신 디바이스 토큰으로 업데이트합니다. | | `INVALID_ARGUMENT` | `InvalidNotification` | 알림 본문이 유효하지 않습니다. | 디바이스 토큰 또는 메시지 페이로드가 유효하지 않을 수 있습니다. 메시지 페이로드가 유효한지 확인합니다. 메시지 페이로드가 유효한 경우 Amazon SNS 엔드포인트를 최신 디바이스 토큰으로 업데이트합니다. | | `SENDER_ID_MISMATCH` | `InvalidPlatformToken` | 엔드포인트와 연결된 플랫폼 토큰이 유효하지 않습니다. | 디바이스 토큰과 연결된 플랫폼 애플리케이션에는 디바이스 토큰으로 전송할 권한이 없습니다. Amazon SNS 플랫폼 애플리케이션에서 올바른 FCM 자격 증명을 사용하고 있는지 확인합니다. | | `UNAVAILABLE` | `DependencyUnavailable` | 종속성을 사용할 수 없습니다. | FCM에서 요청을 처리할 수 없습니다. Amazon SNS에서 실행한 모든 재시도가 실패했습니다. 이러한 메시지를 DLQ(Dad-Letter Queue)에 저장하고 나중에 다시 구동할 수 있습니다. | | `INTERNAL` | `UnexpectedFailure` | 예기치 않은 실패. Amazon에 문의하세요. 실패 문구 [내부 오류]. | 요청을 처리하는 도중 FCM 서버에서 오류가 발생하였습니다. Amazon SNS에서 실행한 모든 재시도가 실패했습니다. 이러한 메시지를 Dead Letter Queue(DLQ)에 저장하고 나중에 다시 구동할 수 있습니다. | | `THIRD_PARTY_AUTH_ERROR` | `InvalidCredentials` | 플랫폼 애플리케이션 자격 증명이 유효하지 않습니다. | iOS 디바이스 또는 Webpush 디바이스를 대상으로 하는 메시지를 전송할 수 없습니다. 개발 및 프로덕션 자격 증명이 유효한지 확인합니다. | | `QUOTA_EXCEEDED` | `Throttled` | [gcm]로 제한되는 요청입니다. | 메시지 속도 할당량, 디바이스 메시지 속도 할당량 또는 주제 메시지 속도 할당량을 초과했습니다. 이 문제를 해결하는 방법에 대한 자세한 내용은 Google *Firebase* 설명서의 에서 [ErrorCode](https://firebase.google.com/docs/reference/fcm/rest/v1/ErrorCode)를 참조하세요. | | `PERMISSION_DENIED` | `InvalidNotification` | 알림 본문이 유효하지 않습니다. | `PERMISSION_DENIED` 예외의 경우 호출자(FCM 애플리케이션)는 페이로드에서 지정된 작업을 실행할 권한이 없습니다. FCM 콘솔로 이동하여 자격 증명에 필요한 API 작업이 활성화되어 있는지 확인합니다. |