Bạn không bắt buộc phải triển khai máy chủ. Hãy sử dụng dịch vụ Mã nhận dạng thực thể nếu bạn muốn thực hiện các thao tác này:
- Xem thông tin về các phiên bản ứng dụng. Xác minh mã thông báo của ứng dụng hoặc nhận thêm thông tin về phiên bản ứng dụng đã tạo mã thông báo.
- Tạo bản đồ mối quan hệ cho các phiên bản ứng dụng. Tạo mối quan hệ giữa các phiên bản của ứng dụng và thực thể như chủ đề FCM hoặc GCM.
- Tạo mã thông báo đăng ký cho mã thông báo APN. API này cho phép bạn nhập hàng loạt mã thông báo APN hiện có, liên kết các mã đó với mã thông báo đăng ký hợp lệ cho FCM hoặc GCM.
- Quản lý mã thông báo đăng ký cho các gói thuê bao đẩy. Đối với các ứng dụng web được triển khai bằng API đẩy, hãy nhập các gói thuê bao đẩy hiện có, ánh xạ các gói thuê bao đó tới mã thông báo đăng ký hợp lệ cho FCM.
Nhận thông tin về các bản sao ứng dụng
Để nhận thông tin về một phiên bản ứng dụng, hãy gọi dịch vụ ID phiên bản tại điểm cuối này, cung cấp mã của phiên bản ứng dụng như sau:
https://iid.googleapis.com/iid/info/IID_TOKEN
Các tham số
Authorization
: key=YOUR_API_KEY. Đặt thông số này trong tiêu đề.- [không bắt buộc] boolean
details
: đặt thông số truy vấn này thànhtrue
để nhận thông tin đăng ký chủ đề FCM hoặc GCM (nếu có) được liên kết với mã thông báo này. Khi không được chỉ định, giá trị mặc định sẽ làfalse
.
Kết quả
Khi thành công, lệnh gọi sẽ trả về trạng thái HTTP 200 và đối tượng JSON chứa:
application
– tên gói liên kết với mã thông báo.authorizedEntity
– projectId được ủy quyền gửi đến mã thông báo.applicationVersion
– phiên bản của ứng dụng.appSigner
– vân taysha1
cho chữ ký được áp dụng cho gói. Cho biết bên nào đã ký ứng dụng; ví dụ:Play Store
.platform
– trả vềANDROID
,IOS
hoặcCHROME
để cho biết nền tảng thiết bị chứa mã thông báo.
Nếu cờ details
được đặt:
rel
– các mối quan hệ liên kết với mã thông báo. Ví dụ: danh sách gói thuê bao theo chủ đề.
Ví dụ về yêu cầu GET
https://iid.googleapis.com/iid/info/nKctODamlM4:CKrh_PC8kIb7O...clJONHoA?Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA
Kết quả mẫu
HTTP 200 OK
{
"application":"com.iid.example",
"authorizedEntity":"123456782354",
"platform":"Android",
"appSigner":"1a2bc3d4e5"
"rel":{
"topics":{
"topicname1":{"addDate":"2015-07-30"},
"topicname2":{"addDate":"2015-07-30"},
"topicname3":{"addDate":"2015-07-30"},
"topicname4":{"addDate":"2015-07-30"}
}
}
}
Tạo bản đồ mối quan hệ cho các bản sao ứng dụng
API Instance ID cho phép bạn tạo bản đồ mối quan hệ cho các phiên bản ứng dụng. Ví dụ: bạn có thể liên kết mã thông báo đăng ký với một chủ đề Nhắn tin qua đám mây của Google, đăng ký bản sao ứng dụng theo chủ đề. API này cung cấp các phương thức để tạo mối quan hệ như vậy cả trên mạng riêng lẻ lẫn hàng loạt.
Tạo mối liên kết mối quan hệ cho một phiên bản ứng dụng
Do có mã thông báo đăng ký và một mối quan hệ được hỗ trợ, bạn có thể tạo một liên kết. Ví dụ: bạn có thể đăng ký một phiên bản ứng dụng vào một chủ đề Nhắn tin qua đám mây của Google bằng cách gọi dịch vụ ID phiên bản tại điểm cuối này, cung cấp mã thông báo của phiên bản ứng dụng như sau:
https://iid.googleapis.com/iid/v1/IID_TOKEN/rel/topics/TOPIC_NAME
Các tham số
Authorization
: key=YOUR_API_KEY. Đặt thông số này trong tiêu đề.
Kết quả
Khi thành công, lệnh gọi sẽ trả về trạng thái HTTP 200.
Ví dụ về yêu cầu POST
https://iid.googleapis.com/iid/v1/nKctODamlM4:CKrh_PC8kIb7O...clJONHoA/rel/topics/movies
Content-Type:application/json
Content-Length: 0
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA
Kết quả mẫu
HTTP 200 OK
{}
Quản lý bản đồ mối quan hệ cho nhiều phiên bản ứng dụng
Bằng cách sử dụng các phương thức hàng loạt của dịch vụ Mã bản sao, bạn có thể quản lý các bản sao ứng dụng theo lô. Ví dụ: bạn có thể thực hiện thêm hoặc xóa hàng loạt bản sao ứng dụng đến một chủ đề FCM hoặc GCM. Để cập nhật tối đa 1000 phiên bản ứng dụng cho mỗi lệnh gọi API, hãy gọi dịch vụ Mã bản sao tại điểm cuối này, cung cấp mã thông báo bản sao ứng dụng trong nội dung JSON:
https://iid.googleapis.com/iid/v1:batchAdd
https://iid.googleapis.com/iid/v1:batchRemove
Các tham số
Authorization
: key=YOUR_API_KEY. Đặt thông số này trong tiêu đề.to
: Tên chủ đề.registration_tokens
: Dãy mã thông báo IID cho những phiên bản ứng dụng mà bạn muốn thêm hoặc xoá.
Kết quả
Khi thành công, lệnh gọi sẽ trả về trạng thái HTTP 200. Kết quả trống cho biết mã thông báo đăng ký thành công. Đối với các gói thuê bao không thành công, kết quả chứa một trong các mã lỗi sau:
- NOT_FOUND — Mã thông báo đăng ký đã bị xóa hoặc ứng dụng đã bị gỡ cài đặt.
- INVALID_ISBN — Mã thông báo đăng ký đã cung cấp không hợp lệ đối với ID người gửi.
- NỘI BỘ — Máy chủ phụ trợ không thành công vì lý do không xác định. Thử gửi lại yêu cầu.
- TOO_MANY_TOPIC — Quá nhiều chủ đề cho mỗi phiên bản ứng dụng.
- RESOURCE_EXHAUSTED — Quá nhiều yêu cầu đăng ký hoặc huỷ đăng ký trong một khoảng thời gian ngắn. Thử lại với thời gian đợi luỹ thừa.
Ví dụ về yêu cầu POST
https://iid.googleapis.com/iid/v1:batchAdd
Content-Type:application/json
Authorization:key=API_KEY
{
"to": "/topics/movies",
"registration_tokens": ["nKctODamlM4:CKrh_PC8kIb7O...", "1uoasi24:9jsjwuw...", "798aywu:cba420..."],
}
Kết quả mẫu
HTTP 200 OK
{
"results":[
{},
{"error":"NOT_FOUND"},
{},
]
}
Tạo mã thông báo đăng ký cho mã thông báo APN
Bằng cách sử dụng phương thức batchImport
của dịch vụ Mã phiên bản, bạn có thể nhập hàng loạt mã thông báo APN iOS hiện có vào dịch vụ Nhắn tin qua đám mây của Google hoặc Giải pháp gửi thông báo qua đám mây của Firebase, liên kết các mã đó với mã thông báo đăng ký hợp lệ. Gọi dịch vụ Mã nhận dạng thực thể tại điểm cuối này, cung cấp danh sách mã thông báo APN trong phần nội dung JSON:
https://iid.googleapis.com/iid/v1:batchImport
Phần nội dung phản hồi chứa một loạt mã thông báo đăng ký mã nhận dạng thực thể đã sẵn sàng dùng để gửi thông báo FCM hoặc GCM tới mã thông báo thiết bị APN tương ứng.
Các tham số
Authorization
: key=YOUR_API_KEY. Đặt thông số này trong tiêu đề.application
: Mã nhận dạng gói của ứng dụng.sandbox
: Boolean để chỉ môi trường hộp cát (TRUE) hoặc sản xuất (FALSE)apns_tokens
: Dãy mã thông báo APN cho các phiên bản ứng dụng mà bạn muốn thêm hoặc xoá. Tối đa 100 mã thông báo mỗi yêu cầu.
Kết quả
Khi thành công, lệnh gọi sẽ trả về trạng thái HTTP 200 và nội dung kết quả JSON. Đối với mỗi mã thông báo APN được cung cấp trong yêu cầu, danh sách kết quả sẽ bao gồm:
- Mã thông báo APN.
- Trạng thái. OK hoặc thông báo lỗi mô tả lỗi.
- Để có kết quả thành công, mã thông báo đăng ký mà FCM hoặc GCM liên kết với mã thông báo APN.
Ví dụ về yêu cầu POST
https://iid.googleapis.com/iid/v1:batchImport
{
"application": "com.google.FCMTestApp",
"sandbox":false,
"apns_tokens":[
"368dde283db539abc4a6419b1795b6131194703b816e4f624ffa12",
"76b39c2b2ceaadee8400b8868c2f45325ab9831c1998ed70859d86"
]
}
}
Kết quả mẫu
HTTP 200 OK
{
"results":[
{
"apns_token": "368dde283db539abc4a6419b1795b6131194703b816e4f624ffa12",
"status": "OK",
"registration_token":"nKctODamlM4:CKrh_PC8kIb7O...clJONHoA"
},
{
"apns_token": "76b39c2b2ceaadee8400b8868c2f45325ab9831c1998ed70859d86",
"status":"Internal Server Error"
},
]
}
Quản lý mã thông báo đăng ký cho các gói thuê bao đẩy
Bằng cách sử dụng các phương thức Web của dịch vụ ID phiên bản, bạn có thể nhập các gói thuê bao đẩy hiện có cho Giải pháp gửi thông báo qua đám mây của Firebase. Bạn cũng có thể cập nhật và xoá các ứng dụng đó.
Khi nhập một gói thuê bao đẩy, bạn sẽ nhận được mã thông báo đăng ký. Mã thông báo này cho phép bạn sử dụng các tính năng FCM như nhắn tin theo chủ đề và nhắn tin nhóm thiết bị để nhắm mục tiêu thông báo đến các ứng dụng web của bạn.
Nhập gói thuê bao đẩy
Bạn có thể nhập các gói thuê bao đẩy bằng điểm cuối web của InstanceID:
https://iid.googleapis.com/v1/web/iid
Yêu cầu phải chứa tiêu đề ủy quyền được đặt thành mã truy cập OAuth 2.0, tiêu đề khoá mã hoá được đặt thành khoá máy chủ ứng dụng và đối tượng PushSubscription
trong nội dung yêu cầu.
Nội dung phản hồi chứa mã thông báo đăng ký sẵn sàng dùng để gửi thông báo FCM hoặc GCM tới phiên bản ứng dụng web tương ứng mà không phải mã hóa trọng tải.
Tải cặp khoá VAPID lên bảng điều khiển
Để nhập khoá, bạn phải có quyền truy cập ở cấp độ chủ sở hữu vào dự án Firebase. Nhập khoá công khai và riêng tư hiện có của bạn ở biểu mẫu mã hoá an toàn cho URL 64:
- Mở thẻ Gửi thông báo qua đám mây của ngăn Cài đặt của Bảng điều khiển của Firebase rồi cuộn đến phần Cấu hình web.
- Trong thẻ Chứng chỉ Web Push, hãy tìm và chọn văn bản liên kết, "nhập một cặp khoá hiện có".
- Trong hộp thoại Nhập cặp khóa, cung cấp khóa công khai và riêng tư của bạn vào các trường tương ứng và nhấp vào Nhập. Bảng điều khiển hiển thị ngày và chuỗi khoá công khai đã thêm.
Truy xuất mã thông báo OAuth2: Sử dụng thông tin xác thực để tạo mã truy cập mint
Để tạo mã truy cập cho yêu cầu này, bạn cần phải tạo mã truy cập và thêm mã đó vào yêu cầu HTTP.
nút.js
function getAccessToken() {
return admin.credential.applicationDefault().getAccessToken()
.then(accessToken => {
return accessToken.access_token;
})
.catch(err => {
console.error('Unable to get access token');
console.error(err);
});
}
Python
def _get_access_token():
"""Retrieve a valid access token that can be used to authorize requests.
:return: Access token.
"""
credentials = ServiceAccountCredentials.from_json_keyfile_name(
'service-account.json', SCOPES)
access_token_info = credentials.get_access_token()
return access_token_info.access_token
Java
private static String getAccessToken() throws IOException {
GoogleCredentials googleCredentials = GoogleCredentials
.fromStream(new FileInputStream("service-account.json"))
.createScoped(Arrays.asList(SCOPES));
googleCredentials.refreshAccessToken();
return googleCredentials.getAccessToken().getTokenValue();
}
Để cho phép truy cập vào FCM, hãy yêu cầu phạm vi
https://www.googleapis.com/auth/firebase.messaging
.
Các tham số
- Uỷ quyền:
Bearer <access_token>
. Đặt thông số này trong tiêu đề. - Khoá mã hoá:
p256ecdsa=APPLICATION_PUBLIC_KEY
. Đặt thông số này trong tiêu đề. - Nội dung yêu cầu:
PushSubscription.toJson()
. Chuyển gói thuê bao đẩy đến nội dung HTTP mà không cần phân tích cú pháp. Nội dung khớp với mã hoá W3C củaPushSubscription
.
Phản hồi
Khi thành công, lệnh gọi sẽ trả về trạng thái HTTP 200 OK và nội dung kết quả JSON chứa mã thông báo IID.
Ví dụ về yêu cầu POST
https://iid.googleapis.com/v1/web/iid
Content-Type:application/json
Authorization:Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
Crypto-Key:p256ecdsa=BFv5XHxdkZgpQzCb-...8uI42kf4A4USEIMo
{
"endpoint": "https://fcm.googleapis.com/fcm/send/dS4xerbSlqU:APb...aRs4QP",
"keys": {
"auth": "7cdY...xxjwz46Q",
"p256dh": "BH7xPjScJe...z9lbIZDmOV_c"
}
}
Kết quả mẫu
HTTP 200 OK
{
"token":"KctODamlM4:CKrh_PC...cl"
}
Cập nhật gói thuê bao đẩy
Bạn có thể cập nhật gói thuê bao đẩy được liên kết với mã thông báo đăng ký của mình bằng cách sử dụng điểm cuối sau:
https://iid.googleapis.com/v1/web/iid/REGISTRATION_TOKEN:refresh
Các tham số
- Uỷ quyền:
Bearer <access_token>
. Đặt thông số này trong tiêu đề. - Khoá mã hoá:
p256ecdsa=APPLICATION_PUBLIC_KEY
. Đặt thông số này trong tiêu đề. - Nội dung yêu cầu:
PushSubscription.toJson()
. Chuyển gói thuê bao đẩy đến nội dung HTTP mà không cần phân tích cú pháp. Nội dung khớp với mã hoá W3C củaPushSubscription
.
Kết quả
Khi thành công, lệnh gọi sẽ trả về trạng thái HTTP 200 và mã thông báo đăng ký. Đây có thể là mã mà bạn đã chuyển trong yêu cầu hoặc là mã thông báo mới.
HTTP 200 OK
{
"token":"KctODamlM4:CKrh_PC...cl"
}
Ví dụ về yêu cầu POST
https://iid.googleapis.com/v1/web/iid/KctODamlM4:CKrh_PC...cl:refresh
Content-Type:application/json
Authorization:Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
Crypto-Key:p256ecdsa=BFv5XHxdkZgpQzCb-...8uI42kf4A4USEIMo
{
"endpoint": "https://fcm.googleapis.com/fcm/send/dS4xerbSlqU:APb...aRs4QP",
"keys": {
"auth": "7cdY...xxjwz46Q"",
"p256dh": "BH7xPjScJe...z9lbIZDmOV_c"
}
}
Kết quả mẫu
HTTP 200 OK
{
"token":"KctODamlM4:CI2k_HHw...3P1"
}
Xoá gói thuê bao đẩy
Yêu cầu DELETE
xoá thông tin đăng ký đẩy khỏi cơ sở dữ liệu FCM. Bạn vẫn có thể nhận thông báo trong ứng dụng web của mình bằng cách sử dụng giao thức Push API.
Để xoá gói thuê bao đẩy, hãy gửi yêu cầu DELETE
đến:
https://iid.googleapis.com/v1/web/iid/REGISTRATION_TOKEN
Ví dụ về yêu cầu DELETE
https://iid.googleapis.com/v1/web/iid/KctODamlM4:CI2k_HHw...3P1
Authorization:Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
Kết quả mẫu
HTTP 200 OK {}
Phản hồi lỗi
Các lệnh gọi đến API máy chủ mã nhận dạng sẽ trả về các mã lỗi HTTP sau đây:
HTTP status 400 (Bad request)
– thiếu tham số hoặc yêu cầu không hợp lệ. Hãy kiểm tra thông báo lỗi để biết thông tin chi tiết.HTTP status 401 (Unauthorized)
– tiêu đề ủy quyền không hợp lệ.HTTP status 403 (Forbidden)
– tiêu đề ủy quyền không khớp vớiauthorizedEntity
.HTTP status 404 (Not found)
– Không tìm thấy đường dẫn HTTP hoặc mã thông báo IID không hợp lệ. Hãy kiểm tra thông báo lỗi để biết thông tin chi tiết.HTTP status 503 (Service unavailable)
– không sử dụng được dịch vụ. Thử lại yêu cầu bằng thuật toán thời gian đợi luỹ thừa.