QQ小游戲 網(wǎng)絡(luò)

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

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

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

配置流程

服務(wù)器域名請在 「小程序后臺-設(shè)置-開發(fā)設(shè)置-服務(wù)器域名」 中進(jìn)行配置，配置時需要注意：

1. 域名只支持 https (qq.request、qq.uploadFile、qq.downloadFile ) 和 wss (qq.connectSocket) 協(xié)議；
2. 域名不能使用 IP 地址或 localhost；
3. 可以配置端口，如 https://myserver.com:8080，但是配置后只能向 https://myserver.com:8080 發(fā)起請求。如果向 https://myserver.com、https://myserver.com:9091 等 URL 請求則會失敗。
4. 如果不配置端口。如 https://myserver.com，那么請求的 URL 中也不能包含端口，甚至是默認(rèn)的 443 端口也不可以。如果向 https://myserver.com:443 請求則會失敗。
5. 域名必須經(jīng)過 ICP 備案；
6. 對于每個接口，分別可以配置最多 20 個域名。

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

超時時間

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

返回值編碼

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

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

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

3. 常見問題

HTTPS 證書

小程序必須使用 HTTPS/WSS 發(fā)起網(wǎng)絡(luò)請求。請求時系統(tǒng)會對服務(wù)器域名使用的 HTTPS 證書進(jìn)行校驗，如果校驗失敗，則請求不能成功發(fā)起。由于系統(tǒng)限制，不同平臺對于證書要求的嚴(yán)格程度不同。為了保證小程序的兼容性，建議開發(fā)者按照最高標(biāo)準(zhǔn)進(jìn)行證書配置，并使用相關(guān)工具檢查現(xiàn)有證書是否符合要求。 對證書要求如下：

• HTTPS 證書必須有效；
  • 證書必須被系統(tǒng)信任，即根證書被已系統(tǒng)內(nèi)置
  • 部署 SSL 證書的網(wǎng)站域名必須與證書頒發(fā)的域名一致
  • 證書必須在有效期內(nèi)
  • 證書的信任鏈必需完整（需要服務(wù)器配置）
• iOS 不支持自簽名證書;
• iOS 下證書必須滿足蘋果 App Transport Security (ATS) 的要求;
• TLS 必須支持 1.2 及以上版本。部分舊 Android 機(jī)型還未支持 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)異常，也請按上述流程進(jìn)行檢查。如 https 的圖片無法加載、音視頻無法播放等。

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

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

跳過域名校驗

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

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

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