QQ小程序 網(wǎng)絡(luò)

2020-07-02 10:05 更新

使用說明

在小程序/小游戲中使用網(wǎng)絡(luò)相關(guān)的 API 時,需要注意下列問題,請開發(fā)者提前了解。

1. 服務(wù)器域名配置

每個QQ小程序需要事先設(shè)置一個通訊域名,小程序只可以跟指定的域名與進行網(wǎng)絡(luò)通信。包括普通 HTTPS 請求(qq.request)、上傳文件(qq.uploadFile)、下載文件(qq.downloadFile) 和 WebSocket 通信(qq.connectSocket

配置流程

  • 服務(wù)器域名請在 「小程序后臺-設(shè)置-開發(fā)設(shè)置-服務(wù)器域名」 中進行配置,配置時需要注意:
  • 域名只支持 https (qq.request、qq.uploadFile、qq.downloadFile) 和 wss (qq.connectSocket) 協(xié)議;
  • 域名不能使用 IP 地址或 localhost;
  • 可以配置端口,如 https://QQminiApp.com:8080,但是配置后只能向 https://QQminiApp.com:8080 發(fā)起請求。如果向 https://QQminiApp.com、https://QQminiApp.com:9091 等 URL 請求則會失敗。
  • 如果不配置端口。如 https://QQminiApp.com,那么請求的 URL 中也不能包含端口,甚至是默認(rèn)的 443 端口也不可以。如果向 https://QQminiApp.com:443 請求則會失敗。
  • 域名必須經(jīng)過 ICP 備案;
  • 出于安全考慮,api.q.qq.com 不能被配置為服務(wù)器域名,相關(guān)API也不能在小程序內(nèi)調(diào)用。 開發(fā)者應(yīng)將 AppSecret 保存到后臺服務(wù)器中,通過服務(wù)器使用 getAccessToken 接口獲取 access_token,并調(diào)用相關(guān) API;
  • 對于每個接口,分別可以配置最多 20 個域名。

2. 網(wǎng)絡(luò)請求

超時時間

  • 默認(rèn)超時時間和最大超時時間都是 60s;
  • 超時時間可以在 app.json 中配置。

使用限制

  • 網(wǎng)絡(luò)請求的 referer header 不可設(shè)置。其格式固定為 https://appservice.qq.com/{appid}/{version}/page-frame.html,其中 {appid} 為小程序的 appid,{version} 為小程序的版本號,版本號為 0 表示為開發(fā)版、體驗版以及審核版本,版本號為 devtools 表示為開發(fā)者工具,其余為正式版本;
  • qq.request、qq.uploadFile、qq.downloadFile 的最大并發(fā)限制是 10 個;
  • 小程序進入后臺運行后(非置頂聊天),如果 5s 內(nèi)網(wǎng)絡(luò)請求沒有結(jié)束,會回調(diào)錯誤信息 fail interrupted;在回到前臺之前,網(wǎng)絡(luò)請求接口調(diào)用都會無法調(diào)用。

返回值編碼

  • 建議服務(wù)器返回值使用 UTF-8 編碼。對于非 UTF-8 編碼,小程序會嘗試進行轉(zhuǎn)換,但是會有轉(zhuǎn)換失敗的可能。
  • 小程序會自動對 BOM 頭進行過濾(只過濾一個BOM頭)。

回調(diào)函數(shù)

  • 只要成功接收到服務(wù)器返回,無論 statusCode 是多少,都會進入 success 回調(diào)。請開發(fā)者根據(jù)業(yè)務(wù)邏輯對返回值進行判斷。

  • HTTPS 證書必須有效;
    • 證書必須被系統(tǒng)信任,即根證書被已系統(tǒng)內(nèi)置
    • 部署 SSL 證書的網(wǎng)站域名必須與證書頒發(fā)的域名一致
    • 證書必須在有效期內(nèi)
    • 證書的信任鏈必需完整(需要服務(wù)器配置)
  • iOS 不支持自簽名證書;
  • iOS 下證書必須滿足蘋果 App Transport Security (ATS) 的要求;
  • TLS 必須支持 1.2 及以上版本。部分舊 Android 機型還未支持 TLS 1.2,請確保 HTTPS 服務(wù)器的 TLS 版本支持 1.2 及以下版本;
  • 部分 CA 可能不被操作系統(tǒng)信任,請開發(fā)者在選擇證書時注意小程序和各系統(tǒng)的相關(guān)通告

證書有效性可以使用 openssl s_client -connect example.com:443 命令驗證,也可以使用其他在線工具

除了網(wǎng)絡(luò)請求 API 外,小程序中其他 HTTPS 請求如果出現(xiàn)異常,也請按上述流程進行檢查。如 https 的圖片無法加載、音視頻無法播放等。

跳過域名校驗

在QQ開發(fā)者工具中,可以臨時開啟 開發(fā)環(huán)境不校驗請求域名、TLS版本及HTTPS證書 選項,跳過服務(wù)器域名的校驗。此時,在QQ開發(fā)者工具中及手機開啟調(diào)試模式時,不會進行服務(wù)器域名的校驗。

在服務(wù)器域名配置成功后,建議開發(fā)者關(guān)閉此選項進行開發(fā),并在各平臺下進行測試,以確認(rèn)服務(wù)器域名配置正確。

如果手機上出現(xiàn) “打開調(diào)試模式可以發(fā)出請求,關(guān)閉調(diào)試模式無法發(fā)出請求” 的現(xiàn)象,請確認(rèn)是否跳過了域名校驗,并確認(rèn)服務(wù)器域名和證書配置是否正確。

以上內(nèi)容是否對您有幫助:
在線筆記
App下載
App下載

掃描二維碼

下載編程獅App

公眾號
微信公眾號

編程獅公眾號