Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# Menerbitkan notifikasi Amazon SNS dengan muatan khusus platform
Anda dapat menggunakan Amazon SNS Konsol Manajemen AWS atau APIs untuk mengirim pesan khusus dengan muatan khusus platform ke perangkat seluler. Untuk informasi tentang menggunakan Amazon SNS APIs, lihat [Tindakan API push seluler](mobile-push-api.md) dan `SNSMobilePush.java` file di. `[snsmobilepush.zip](samples/snsmobilepush.zip)`
## Mengirim pesan berformat JSON
Saat Anda mengirim muatan khusus platform, data harus diformat sebagai string pasangan nilai kunci JSON, dengan tanda kutip diloloskan.
Contoh berikut menunjukkan pesan khusus untuk platform FCM.
```
{
"GCM": "{\"fcmV1Message\": {\"message\": {\"notification\": {\"title\": \"Hello\", \"body\": \"This is a test.\"}, \"data\": {\"dataKey\": \"example\"}}}}"
}
```
## Mengirim pesan khusus platform
Selain mengirim data khusus sebagai pasangan nilai kunci, Anda dapat mengirim pasangan nilai kunci khusus platform.
Contoh berikut menunjukkan penyertaan parameter FCM `time_to_live` dan `collapse_key` setelah pasangan nilai kunci data kustom dalam parameter `data` FCM.
```
{
"GCM": "{\"fcmV1Message\": {\"message\": {\"notification\": {\"title\": \"TitleTest\", \"body\": \"Sample message for Android or iOS endpoints.\"}, \"data\":{\"time_to_live\": 3600,\"collapse_key\":\"deals\"}}}}"
}
```
Untuk daftar pasangan kunci-nilai yang didukung oleh masing-masing layanan notifikasi push yang didukung di Amazon SNS, lihat berikut ini:
**penting**
Amazon SNS sekarang mendukung Firebase Cloud Messaging (FCM) HTTP v1 API untuk mengirimkan notifikasi push seluler ke perangkat Android.
26 Maret 2024 - Amazon SNS mendukung FCM HTTP v1 API untuk perangkat Apple dan tujuan Webpush. Kami menyarankan Anda memigrasikan aplikasi push seluler yang ada ke FCM HTTP v1 API terbaru pada atau sebelum 1 Juni 2024 untuk menghindari gangguan aplikasi.
+ [Referensi Kunci Payload](https://developer.apple.com/library/archive/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/PayloadKeyReference.html#/apple_ref/doc/uid/TP40008194-CH17-SW1) dalam dokumentasi APNs
+ [Protokol HTTP Firebase Cloud Messaging](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages) dalam dokumentasi FCM
+ [Kirim Pesan](https://developer.amazon.com/sdk/adm/sending-message.html) di dokumentasi ADM
## Mengirim pesan ke aplikasi di berbagai platform
Untuk mengirim pesan ke aplikasi yang diinstal pada perangkat untuk beberapa platform, seperti FCM dan APNs, Anda harus terlebih dahulu berlangganan titik akhir seluler ke topik di Amazon SNS dan kemudian mempublikasikan pesan ke topik tersebut.
Contoh berikut menunjukkan pesan untuk dikirim ke endpoint seluler berlangganan pada APNs, FCM, dan 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\"}}"
}
```
## Mengirim pesan ke APNs sebagai peringatan atau pemberitahuan latar belakang
Amazon SNS dapat mengirim pesan ke APNs as `alert` atau `background` notifikasi (untuk informasi selengkapnya, lihat [Mendorong Pembaruan Latar Belakang ke Aplikasi Anda](https://developer.apple.com/documentation/usernotifications/setting_up_a_remote_notification_server/pushing_background_updates_to_your_app) dalam APNs dokumentasi).
+ `alert` APNs Pemberitahuan menginformasikan pengguna dengan menampilkan pesan peringatan, memutar suara, atau menambahkan lencana ke ikon aplikasi Anda.
+ `background` APNs Pemberitahuan bangun atau menginstruksikan aplikasi Anda untuk bertindak atas konten pemberitahuan, tanpa memberi tahu pengguna.
### Menentukan nilai APNs header kustom
Sebaiknya tentukan nilai kustom untuk [atribut pesan yang `AWS.SNS.MOBILE.APNS.PUSH_TYPE` dicadangkan](sns-message-attributes.md#sns-attrib-mobile-reserved) menggunakan tindakan Amazon `Publish` SNS API AWS SDKs, atau. AWS CLI Contoh CLI berikut menyetel `content-available` ke `1` dan `apns-push-type` ke `background` untuk topik yang ditentukan.
```
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
```
**catatan**
Pastikan bahwa struktur JSON valid. Tambahkan koma setelah setiap pasangan kunci-nilai, kecuali yang terakhir.
### Menyimpulkan header tipe APNs push dari payload
Jika Anda tidak menyetel `apns-push-type` APNs header, Amazon SNS menetapkan header ke `alert` atau `background` bergantung pada `content-available` kunci dalam `aps` kamus konfigurasi payload berformat APNs JSON Anda.
**catatan**
Amazon SNS hanya dapat menyimpulkan header `alert` atau `background`, meskipun header `apns-push-type` dapat diatur ke nilai lain.
+ `apns-push-type` diatur ke `alert`
+ Jika kamus `aps` berisi `content-available` yang diatur ke `1` dan *satu atau beberapa kunci* yang memicu interaksi pengguna.
+ Jika kamus `aps` berisi `content-available` yang diatur ke `0` *atau* jika kunci `content-available` tidak ada.
+ Jika nilai kunci `content-available` bukan bilangan bulat atau Boolean.
+ `apns-push-type` diatur ke `background`
+ Jika kamus `aps` *hanya* berisi `content-available` yang diatur ke `1` dan *tidak ada kunci lain* yang memicu interaksi pengguna.
**penting**
Jika Amazon SNS mengirimkan objek konfigurasi mentah APNs sebagai notifikasi khusus latar belakang, Anda harus menyertakan `content-available` set ke dalam kamus. `1` `aps` Meskipun Anda dapat menyertakan kunci kustom, kamus `aps` tidak boleh berisi kunci apa pun yang memicu interaksi pengguna (misalnya, peringatan, lencana, atau suara).
Berikut ini adalah contoh objek konfigurasi mentah.
```
{
"APNS": "{\"aps\":{\"content-available\":1},\"Foo1\":\"Bar\",\"Foo2\":123}"
}
```
Dalam contoh ini, Amazon SNS menyetel `apns-push-type` APNs header untuk pesan tersebut. `background` Saat Amazon SNS mendeteksi bahwa kamus `apn` berisi kunci `content-available` yang diatur ke `1`—dan tidak berisi kunci lain yang dapat memicu interaksi pengguna—itu menyetel header ke `background`.
# Menggunakan payload Google Firebase Cloud Messaging v1 di Amazon SNS
Amazon SNS mendukung penggunaan FCM HTTP v1 API untuk mengirim notifikasi ke tujuan Android, iOS, dan Webpush. Topik ini memberikan contoh struktur payload saat menerbitkan notifikasi push seluler menggunakan CLI, atau Amazon SNS API.
Anda dapat menyertakan jenis pesan berikut di payload saat mengirim notifikasi FCM:
+ **Pesan data** — Pesan data ditangani oleh aplikasi klien Anda dan berisi pasangan nilai kunci khusus. Saat membuat pesan data, Anda harus menyertakan `data` kunci dengan objek JSON sebagai nilainya, lalu masukkan pasangan nilai kunci kustom Anda.
+ **Pesan pemberitahuan atau pesan** **tampilan — Pesan** notifikasi berisi sekumpulan kunci yang telah ditentukan sebelumnya yang ditangani oleh FCM SDK. Tombol-tombol ini bervariasi tergantung pada jenis perangkat yang Anda kirimkan. Untuk informasi selengkapnya tentang kunci notifikasi khusus platform, lihat berikut ini:
+ [Tombol notifikasi Android](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages)
+ [Kunci pemberitahuan APNS](https://developer.apple.com/documentation/usernotifications/generating-a-remote-notification)
+ [Tombol pemberitahuan Webpush](https://developer.mozilla.org/en-US/docs/Web/API/Notification)
Untuk informasi selengkapnya tentang jenis pesan FCM, lihat [Jenis pesan](https://firebase.google.com/docs/cloud-messaging/concept-options#notifications_and_data_messages) di dokumentasi *Firebase* Google.
## Menggunakan struktur payload FCM v1 untuk mengirim pesan
Jika Anda membuat aplikasi FCM untuk pertama kalinya, atau ingin memanfaatkan fitur FCM v1, Anda dapat memilih untuk mengirim muatan berformat FCM v1. Untuk melakukan ini, Anda harus menyertakan kunci `fcmV1Message` tingkat atas. *Untuk informasi selengkapnya tentang membuat payload FCM v1, lihat [Memigrasi dari FCM lama APIs ke HTTP v1](https://firebase.google.com/docs/cloud-messaging/migrate-v1) dan [Menyesuaikan](https://firebase.google.com/docs/cloud-messaging/concept-options#customizing-a-message-across-platforms) pesan di seluruh platform dalam dokumentasi Firebase Google.*
**Contoh payload FCM v1 dikirim ke Amazon SNS:**
**catatan**
Nilai `GCM` kunci yang digunakan dalam contoh berikut harus dikodekan sebagai String saat menerbitkan notifikasi menggunakan 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\"
}
}
}
}
}"
}
```
Saat mengirim payload JSON, pastikan untuk menyertakan `message-structure` atribut dalam permintaan Anda, dan atur ke. `json`
**Contoh 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
```
*Untuk informasi selengkapnya tentang pengiriman payload berformat FCM v1, lihat hal berikut di dokumentasi Firebase Google:*
+ [Migrasi dari FCM APIs lama ke HTTP v1](https://firebase.google.com/docs/cloud-messaging/migrate-v1)
+ [Tentang pesan FCM](https://firebase.google.com/docs/cloud-messaging/concept-options#customizing_a_message_across_platforms)
+ [Sumber Daya REST: projects.messages](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages)
## Menggunakan struktur payload lama untuk mengirim pesan ke FCM v1 API
Saat bermigrasi ke FCM v1, Anda tidak perlu mengubah struktur payload yang Anda gunakan untuk kredensi lama Anda. Amazon SNS mengubah payload Anda menjadi struktur payload FCM v1 baru, dan mengirimkannya ke Google.
Format payload pesan masukan:
```
{
"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\"}}"
}
```
Pesan yang dikirim ke 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"
}
}
}
```
**Potensi risiko**
+ Pemetaan lama ke v1 tidak mendukung Layanan Pemberitahuan Push Apple (APNS) `headers` atau tombol. `fcm_options` Jika Anda ingin menggunakan bidang ini, kirim payload FCM v1.
+ Dalam beberapa kasus, header pesan diperlukan oleh FCM v1 untuk mengirim notifikasi senyap ke perangkat Anda. APNs Jika saat ini Anda mengirim notifikasi senyap ke APNs perangkat Anda, mereka tidak akan berfungsi dengan pendekatan lama. Sebagai gantinya, sebaiknya gunakan payload FCM v1 untuk menghindari masalah yang tidak terduga. Untuk menemukan daftar APNs header dan tujuan penggunaannya, lihat [Berkomunikasi dengan APNs](https://developer.apple.com/library/archive/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/CommunicatingwithAPNs.html) di Panduan *Pengembang Apple*.
+ Jika Anda menggunakan atribut `TTL` Amazon SNS saat mengirim notifikasi, itu hanya akan diperbarui di `android` lapangan. Jika Anda ingin menyetel atribut `TTL` APNS, gunakan payload FCM v1.
+ `webpush`Kunci`android`,`apns`, dan akan dipetakan dan diisi dengan semua kunci yang relevan yang disediakan. Misalnya, jika Anda menyediakan`title`, yang merupakan kunci yang dibagikan di antara ketiga platform, pemetaan FCM v1 akan mengisi ketiga platform dengan judul yang Anda berikan.
+ Beberapa kunci bersama di antara platform mengharapkan jenis nilai yang berbeda. Misalnya, `badge` kunci yang diteruskan untuk `apns` mengharapkan nilai integer, sedangkan `badge` kunci dilewatkan untuk `webpush` mengharapkan nilai String. Dalam kasus di mana Anda memberikan `badge` kunci, pemetaan FCM v1 hanya akan mengisi kunci yang Anda berikan nilai valid.
## Peristiwa kegagalan pengiriman FCM
Tabel berikut menyediakan jenis kegagalan Amazon SNS yang sesuai dengan kode kesalahan/status yang diterima dari Google untuk permintaan notifikasi FCM v1. Semua kode kesalahan yang diamati yang diterima dari FCM v1 API tersedia untuk Anda CloudWatch saat Anda mengatur [pencatatan status pengiriman](topics-attrib.md) untuk aplikasi Anda.
| Kode FCM error/status | Jenis kegagalan Amazon SNS | Pesan kegagalan | Penyebab dan mitigasi |
| --- | --- | --- | --- |
| `UNREGISTERED` | `InvalidPlatformToken` | Token platform yang terkait dengan titik akhir tidak valid. | Token perangkat yang dilampirkan ke titik akhir Anda sudah basi atau tidak valid. Amazon SNS menonaktifkan titik akhir Anda. Perbarui titik akhir Amazon SNS ke token perangkat terbaru. |
| `INVALID_ARGUMENT` | `InvalidNotification` | Badan notifikasi tidak valid. | Token perangkat atau payload pesan mungkin tidak valid. Verifikasi bahwa payload pesan Anda valid. Jika payload pesan valid, perbarui titik akhir Amazon SNS ke token perangkat terbaru. |
| `SENDER_ID_MISMATCH` | `InvalidPlatformToken` | Token platform yang terkait dengan titik akhir tidak valid. | Aplikasi platform yang terkait dengan token perangkat tidak memiliki izin untuk mengirim ke token perangkat. Verifikasi bahwa Anda menggunakan kredensi FCM yang benar di aplikasi platform Amazon SNS Anda. |
| `UNAVAILABLE` | `DependencyUnavailable` | Ketergantungan tidak tersedia. | FCM tidak dapat memproses permintaan tepat waktu. Semua percobaan ulang yang dijalankan oleh Amazon SNS telah gagal. Anda dapat menyimpan pesan-pesan ini dalam antrian huruf mati (DLQ) dan mengaktifkannya kembali nanti. |
| `INTERNAL` | `UnexpectedFailure` | Kegagalan tak terduga; silakan hubungi Amazon. Frasa kegagalan [Kesalahan Internal]. | Server FCM mengalami kesalahan saat mencoba memproses permintaan Anda. Semua percobaan ulang yang dijalankan oleh Amazon SNS telah gagal. Anda dapat menyimpan pesan-pesan ini dalam antrian huruf mati (DLQ) dan mengaktifkannya kembali nanti. |
| `THIRD_PARTY_AUTH_ERROR` | `InvalidCredentials` | Kredensi aplikasi platform tidak valid. | Pesan yang ditargetkan ke perangkat iOS atau perangkat Webpush tidak dapat dikirim. Verifikasi bahwa kredenal pengembangan dan produksi Anda valid. |
| `QUOTA_EXCEEDED` | `Throttled` | Permintaan dibatasi oleh [gcm]. | Kuota rasio pesan, kuota tarif pesan perangkat, atau kuota tarif pesan topik telah terlampaui. Untuk informasi tentang cara mengatasi masalah ini, lihat [ErrorCode](https://firebase.google.com/docs/reference/fcm/rest/v1/ErrorCode)di dokumentasi *Firebase* Google. |
| `PERMISSION_DENIED` | `InvalidNotification` | Badan notifikasi tidak valid. | Dalam kasus `PERMISSION_DENIED` pengecualian, pemanggil (aplikasi FCM Anda) tidak memiliki izin untuk menjalankan operasi yang ditentukan dalam payload. Arahkan ke konsol FCM Anda, dan verifikasi bahwa tindakan API yang diperlukan telah diaktifkan. |