本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 發佈具有平台特定承載的 Amazon SNS 通知
<a name="sns-send-custom-platform-specific-payloads-mobile-devices"></a>

您可以使用 AWS 管理主控台 或 Amazon SNS APIs，將具有平台特定承載的自訂訊息傳送至行動裝置。如需使用 Amazon SNS API 的詳細資訊，請參閱 `[snsmobilepush.zip](samples/snsmobilepush.zip)` 中的 [行動推送 API 動作](mobile-push-api.md) 與 `SNSMobilePush.java` 檔案。

## 傳送 JSON 格式訊息
<a name="mobile-push-send-json"></a>

當您傳送平台特定酬載時，資料格式必須為 JSON 鍵值對字串，並搭配引號逸出。

以下範例說明 FCM 平台的自訂訊息。

```
{
"GCM": "{\"fcmV1Message\": {\"message\": {\"notification\": {\"title\": \"Hello\", \"body\": \"This is a test.\"}, \"data\": {\"dataKey\": \"example\"}}}}"
}
```

## 傳送平台特定訊息
<a name="mobile-push-send-platform"></a>

除了將自訂資料做為鍵值對傳送，您也可傳送平台特定的鍵值對。

以下範例顯示在 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 現在支援 Firebase Cloud Messaging (FCM) HTTP v1 API，可將行動推播通知傳送至 Android 裝置。  
2024 年 3 月 26 日 – Amazon SNS 支援適用於 Apple 裝置和 Webpush 目的地的 FCM HTTP v1 API。我們建議您在 2024 年 6 月 1 日或之前將現有的行動推送應用程式遷移至最新的 FCM HTTP v1 API，以避免應用程式中斷。
+ 在 APN 文件中的[酬載金鑰參考](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)

## 在多個平台上向應用程式傳送訊息
<a name="mobile-push-send-multiplatform"></a>

若要為多個平台 (如 FCM 和 APN) 向裝置上安裝的應用程式傳送訊息，您必須先將行動裝置端點訂閱 Amazon SNS 中的某個主題，然後向該主題發佈訊息。

以下範例顯示要傳送到 APN、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\"}}" 
}
```

## 將訊息做為提醒或背景通知傳送到 APN
<a name="mobile-push-send-message-apns-background-notification"></a>

Amazon SNS 可以將訊息傳送到 APN 作為 `alert` 或 `background` 通知 (如需詳細資訊，請參閱 APN 文件中的[將背景更新推送到您的應用程式](https://developer.apple.com/documentation/usernotifications/setting_up_a_remote_notification_server/pushing_background_updates_to_your_app))。
+ `alert` APN 通知會顯示提醒訊息、播放音效，或將徽章新增到您應用程式的圖示，來通知使用者。
+ `background` APN 通知會喚醒或指示您的應用程式來對通知內容採取行動，而不會通知使用者。

### 指定自訂 APN 標頭數值
<a name="specify-custom-header-value"></a>

建議您使用 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 結構有效。在每個鍵/值對之後新增逗號，最後一個鍵/值對除外。

### 從酬載推論 APN 推送類型標頭
<a name="inferring-push-type-header-from-payload"></a>

如果您沒有設定 `apns-push-type` APN 標頭，依 `content-available` 金鑰而定，Amazon SNS 會在您 JSON 格式 APN 酬載組態的 `aps` 字典中，將標頭設為 `alert` 或 `background`。

**注意**  
雖然 `apns-push-type` 標頭可設為其他值，但 Amazon SNS 僅可推論 `alert` 或 `background` 標頭。
+ `apns-push-type` 已設定為 `alert`
  + 如果 `aps` 字典僅包含設定為 `content-available` 的 `1`，且*一個以上金鑰*可觸發使用者互動。
  + 如果 `aps` 字典包含設定為 `content-available` 的 `0`，*或者* `content-available` 金鑰不存在。
  + 如果 `content-available` 金鑰的值不是整數或布林值。
+ `apns-push-type` 已設定為 `background`
  + 如果 `aps` 字典*僅*包含設定為 `content-available` 的 `1`，且*沒有其他金鑰*可觸發使用者互動。
**重要**  
如果 Amazon SNS 以僅限背景通知的方式傳送 APN 的原始組態物件，那麼您就必須在 `aps` 字典中加入設為 `content-available` 的 `1`。雖然您可以加入自定金鑰，`aps` 字典絕對不能包含可觸發使用者互動的任何金鑰 (例如：通知、徽章或聲音)。

以下是原始組態物件範例。

```
{
  "APNS": "{\"aps\":{\"content-available\":1},\"Foo1\":\"Bar\",\"Foo2\":123}"
}
```

在此範例中，Amazon SNS 會將訊息的 `apns-push-type` APN 標頭設為 `background`。當 Amazon SNS 偵測到 `apn` 字典包含設定為 `1` 的 `content-available` 金鑰，且不包含任何其他設定標頭為可觸發使用者互動的金鑰時，會將標頭設為 `background`。