排障指南)
上周又有人在群里拋截圖面板彈出來了點(diǎn)微信好友轉(zhuǎn)圈兩秒然后沒下文日志里干干凈凈。這種問題十有八九不是 SDK 壞了是接入鏈路上某個(gè)環(huán)節(jié)對(duì)不上。做過 Android Studio 里集成 ShareSDK 做第三方分享的同學(xué)應(yīng)該都懂聚合分享這活兒看著是引個(gè)依賴、調(diào)個(gè) show實(shí)際上從開放平臺(tái)注冊(cè)、簽名指紋、清單文件、回調(diào) Activity 到混淆規(guī)則至少有五六個(gè)地方要同時(shí)對(duì)齊任何一個(gè)錯(cuò)位表現(xiàn)都是同一個(gè)——分享不出去。這篇東西就是把這些環(huán)節(jié)拆開講清楚。ShareSDK 是一套聚合分享組件把微信、QQ、微博、系統(tǒng)分享這些渠道的登錄、分享、回調(diào)收斂成一套統(tǒng)一 API省掉你逐個(gè)接入原生 SDK 的重復(fù)勞動(dòng)適合需要點(diǎn)多面廣分享能力的中大型 App也適合剛接手老項(xiàng)目、被回調(diào)問題折磨的同學(xué)。下面從選型邏輯一路講到線上收尾能直接抄的部分我盡量寫成可復(fù)制的代碼和配置。1. 先把需求拆干凈為什么選聚合分享 SDK 而不是逐個(gè)接原生1.1 逐個(gè)接原生 SDK 的隱性成本遠(yuǎn)高于第一眼看到的很多人做技術(shù)選型時(shí)算的賬是接三個(gè)平臺(tái)的原生 SDK 大概兩天實(shí)際干下來往往是一周。原因不在核心代碼量而在那些看不到的協(xié)調(diào)成本。每個(gè)渠道都要單獨(dú)去開放平臺(tái)注冊(cè)應(yīng)用、填包名、填簽名、等審核每個(gè)渠道的回調(diào) Activity 放在不同的包里、繼承不同的父類、注冊(cè)不同的 intent-filter每個(gè)渠道的分享參數(shù)結(jié)構(gòu)還各不相同——圖片鏈接在 A 平臺(tái)叫 imageUrl在 B 平臺(tái)叫 imageObject壓縮策略和尺寸上限也不一樣。更要命的是這些代碼會(huì)隨平臺(tái)更新而失效。某個(gè)平臺(tái)某次調(diào)整了縮略圖上限你的分享就靜默失敗某個(gè)平臺(tái)把回調(diào)類的包名規(guī)則收緊你的分享成功但 UI 永遠(yuǎn)停在分享中。三套代碼意味著三次回歸測(cè)試四套就是四次。如果產(chǎn)品需求只是能讓用戶把內(nèi)容發(fā)出去這筆投入的性價(jià)比非常低。我見過一個(gè)內(nèi)容類項(xiàng)目最初老老實(shí)實(shí)接了三個(gè)原生 SDK后來產(chǎn)品要加兩個(gè)新渠道評(píng)估下來改動(dòng)量比重新接一遍還大最后整體換成了聚合方案。所以選型時(shí)真正該問的不是聚合 SDK 是不是更輕而是我要維護(hù)的渠道數(shù)量會(huì)不會(huì)變。只要答案是會(huì)聚合方案的優(yōu)勢(shì)就成立。1.2 聚合方案幫你抹平了什么又沒有幫你抹平什么ShareSDK 的核心價(jià)值是把渠道差異收進(jìn) SDK 內(nèi)部對(duì)外只暴露一層統(tǒng)一接口統(tǒng)一初始化、統(tǒng)一平臺(tái)標(biāo)識(shí)、統(tǒng)一分享參數(shù)結(jié)構(gòu)、統(tǒng)一回調(diào)協(xié)議、統(tǒng)一分享面板 UI。你在業(yè)務(wù)層寫一份代碼切換渠道只是換一個(gè)字符串常量。這對(duì)業(yè)務(wù)層是實(shí)打?qū)嵉臏p負(fù)尤其是分享面板這種交互統(tǒng)一、業(yè)務(wù)邏輯薄的功能。但它不是銀彈有幾件事它替你做不了開放平臺(tái)的應(yīng)用注冊(cè)與審核是你自己的賬號(hào)行為包名與簽名的綁定關(guān)系必須你手動(dòng)填對(duì)SDK 沒法猜目標(biāo) App 未安裝時(shí)的降級(jí)體驗(yàn)需要你在業(yè)務(wù)層設(shè)計(jì)圖片資源合規(guī)尺寸、格式、是否公網(wǎng)可訪問依然是調(diào)用方責(zé)任。把這四件事當(dāng)成SDK 應(yīng)該自動(dòng)處理的基本都會(huì)在調(diào)試階段撞墻。理解這一點(diǎn)很重要因?yàn)樗鼪Q定了你的調(diào)試順序。當(dāng)你遇到分享沒反應(yīng)第一反應(yīng)不應(yīng)該是去翻 SDK 源碼而應(yīng)該按賬號(hào)綁定 → 清單文件 → 回調(diào)注冊(cè) → 參數(shù)合法這條鏈路逐段卡點(diǎn)。后面第 4 章的排查表就是按這個(gè)順序排的。1.3 渠道能力矩陣先想清楚哪些渠道真的需要不同渠道的能力差異很大不是所有渠道都值得接。接之前先拿一張表把需求框住能省掉一半工作量。下表是基于常見實(shí)踐的整理具體以你接入時(shí)服務(wù)方文檔為準(zhǔn)渠道是否需要開放平臺(tái)審核是否要求客戶端安裝回調(diào)機(jī)制常見坑點(diǎn)微信好友是需應(yīng)用審核通過是通過 wxapi 包下的回調(diào)類包名/簽名不匹配直接無回調(diào)微信朋友圈是是同上僅支持圖文/鏈接純文本受限QQ / Qzone是是SDK 內(nèi)部廣播 回調(diào)類tencentappId 的 scheme 未聲明微博是是回調(diào)類圖片需先上傳鏈接需備案域名系統(tǒng)分享否否無回調(diào)只能拿到已喚起拿不到結(jié)果這張表最關(guān)鍵的信息其實(shí)是最后一列——只有系統(tǒng)分享是無回調(diào)的其余渠道理論上都能拿到成功/失敗/取消三態(tài)。如果你的產(chǎn)品經(jīng)理要求分享成功給積分那就必須走前四類系統(tǒng)分享只能算兜底入口。另外還要注意一個(gè)產(chǎn)品側(cè)的取舍微信朋友圈對(duì)純文本分享有限制如果你要分享的是純文字內(nèi)容朋友圈渠道實(shí)際上會(huì)失敗需要在 UI 上把該渠道置灰或者自動(dòng)轉(zhuǎn)成生成圖片再分享。這類細(xì)節(jié)在需求評(píng)審階段就該確認(rèn)別等聯(lián)調(diào)時(shí)才發(fā)現(xiàn)。1.4 版本矩陣SDK、構(gòu)建插件、AGP 三者必須對(duì)齊這里單獨(dú)拎出來講因?yàn)樗切率肿钊菀缀雎?、也最容易?dǎo)致編譯過了但運(yùn)行崩的原因。聚合 SDK 通常以 Gradle 插件形式接入負(fù)責(zé)自動(dòng)注入清單、自動(dòng)生成渠道配置這個(gè)插件對(duì) Android Gradle Plugin 的版本是有要求的。AGP 升級(jí)到較新版本后老插件可能無法解析變體信息表現(xiàn)為構(gòu)建期報(bào)找不到 task 或者清單合并失敗。我的建議是把三個(gè)版本號(hào)寫進(jìn)項(xiàng)目文檔并鎖死AGP 版本、Gradle Wrapper 版本、分享 SDK 插件版本。升級(jí) AGP 時(shí)把這三個(gè)一起評(píng)估別單獨(dú)動(dòng)一個(gè)。如果確實(shí)要升級(jí)先在獨(dú)立分支上升跑通初始化 → 分享 → 回調(diào)完整鏈路再合回主干。這個(gè)流程聽起來啰嗦但比線上發(fā)現(xiàn)問題強(qiáng)太多。2. 動(dòng)手之前的三件事賬號(hào)、簽名、工程基線2.1 包名與簽名指紋是繞不過去的硬門檻所有渠道的審核第一步都是你是誰。開放平臺(tái)通過應(yīng)用包名 簽名指紋來識(shí)別調(diào)用方兩者任一不匹配渠道側(cè)會(huì)直接拒絕而客戶端往往拿不到明確錯(cuò)誤只表現(xiàn)為點(diǎn)了沒反應(yīng)。所以這一步必須先做且要用正式發(fā)布用的簽名文件去算指紋不要用 debug 簽名湊數(shù)。取指紋有兩條路。第一條是命令行直接讀 keystorekeytool -list -v \ -keystore release.jks \ -alias your_alias \ -storepass 你的store密碼 \ -keypass 你的key密碼輸出里會(huì)有一行MD5:和一串冒號(hào)分隔的十六進(jìn)制。第二條是 Gradle 自帶的報(bào)告任務(wù)在 Android Studio 的 Terminal 里執(zhí)行./gradlew signingReport它會(huì)把每個(gè)變體用的簽名信息都打出來包括 MD5 和 SHA1很適合確認(rèn)當(dāng)前構(gòu)建到底簽的哪個(gè)文件。我用這條命令查出過一次事故CI 上配置的 keystore 路徑寫錯(cuò)回退到了默認(rèn) debug 簽名本地調(diào)試一切正常出包就全渠道失效。關(guān)于格式這里有個(gè)特別容易被卡住的細(xì)節(jié)不同渠道對(duì)指紋格式要求不一樣。有的要小寫無冒號(hào)有的要大寫帶冒號(hào)有的要 SHA1。填之前把平臺(tái)頁面的輸入框提示看清楚實(shí)在不確定就把大小寫兩種都試一遍。我習(xí)慣在文檔里存一份對(duì)照表包含每個(gè)渠道填的字段、格式、填寫日期換人接手時(shí)不用重新考古。2.2 Gradle 倉庫與插件配置的寫法工程基線部分分三步加倉庫、加插件依賴、加渠道配置。倉庫地址會(huì)隨服務(wù)方調(diào)整而變化我不建議在文章里貼死鏈按你接入時(shí)的官方文檔填即可通常形如// 項(xiàng)目根目錄 build.gradle buildscript { repositories { google() mavenCentral() maven { url SDK服務(wù)方提供的Maven倉庫地址 } // 以官方文檔為準(zhǔn) } dependencies { classpath com.android.tools.build:gradle:8.x.x classpath SDK服務(wù)方提供的構(gòu)建插件坐標(biāo) // 與SDK大版本對(duì)應(yīng) } } allprojects { repositories { google() mavenCentral() maven { url SDK服務(wù)方提供的Maven倉庫地址 } } }然后在 app 模塊里應(yīng)用插件并填寫渠道信息// app/build.gradle apply plugin: com.android.application apply plugin: SDK服務(wù)方提供的插件名 SDK配置塊 { appKey 你的AppKey appSecret 你的AppSecret ShareSDK { devInfo { Wechat { appId wx開頭的AppID appSecret 微信開放平臺(tái)的應(yīng)用密鑰 withShareTicket true bypassApproval false } WechatMoments { appId 同一個(gè)AppID appSecret 同一個(gè)密鑰 bypassApproval false } QQ { appId QQ互聯(lián)的數(shù)字AppID appKey QQ互聯(lián)的AppKey } SinaWeibo { appKey 微博的AppKey appSecret 微博的AppSecret callbackUri https://你的回調(diào)地址 shareByAppClient true } } } }這段配置的本質(zhì)是在編譯期生成渠道清單和初始化參數(shù)所以改完必須重新構(gòu)建光改代碼不重新 sync 是不生效的。我遇到過同事改完配置直接點(diǎn)運(yùn)行結(jié)果用的還是緩存里的舊清單排查了半小時(shí)。養(yǎng)成習(xí)慣改了這段就 Clean 一次。2.3 清單文件幾個(gè)必須手寫的聲明雖然插件會(huì)自動(dòng)注入大部分內(nèi)容但有兩處必須自己寫清楚。第一處是微信回調(diào) Activity它必須放在你的包名.wxapi這個(gè)固定路徑下類名必須是WXEntryActivity少一個(gè)字都收不到回調(diào)package com.example.demo.wxapi; import cn.sharesdk.wechat.utils.WXEntryActivity; public class WXEntryActivity extends WXEntryActivity { // 不需要寫任何代碼父類已經(jīng)處理了回調(diào)分發(fā) }對(duì)應(yīng)清單聲明activity android:name.wxapi.WXEntryActivity android:exportedtrue android:launchModesingleTop android:taskAffinity你的包名 android:themeandroid:style/Theme.Translucent.NoTitleBar /exportedtrue是必須的因?yàn)榛卣{(diào)是從外部應(yīng)用喚起的taskAffinity設(shè)成包名是為了避免多任務(wù)棧里出現(xiàn)重復(fù)頁面。第二處是Android 11 及以上的包可見性聲明不加的話你連微信是否安裝都判斷不出來渠道會(huì)一直顯示為不可用queries package android:namecom.tencent.mm / package android:namecom.tencent.mobileqq / intent action android:nameandroid.intent.action.VIEW / data android:schemeweixin / /intent /queriesQQ 的回調(diào)還需要在清單里聲明tencent加 AppID 的 scheme這個(gè)通常由插件生成但如果你手動(dòng)裁剪過清單記得檢查一遍。我一般會(huì)在集成完成后做一次清單體檢把合并后的清單導(dǎo)出來搜索wxapi、tencent、queries三個(gè)關(guān)鍵字確認(rèn)都在。2.4 混淆規(guī)則和隱私初始化時(shí)機(jī)混淆這塊的規(guī)則不復(fù)雜但漏了就是線上崩潰且往往在灰度階段才發(fā)現(xiàn)-keep class cn.sharesdk.** { *; } -keep class com.mob.** { *; } -keep class com.sina.** { *; } -keep class **.R$* { *; } -keep class **.wxapi.** { *; } -dontwarn cn.sharesdk.** -dontwarn com.mob.**注意最后那條**.wxapi.**很多人只保留了 SDK 包名忘了自己的回調(diào)類也在反射調(diào)用鏈上混淆后類名變了回調(diào)自然分發(fā)不到。另一個(gè)必須提的是隱私合規(guī)?，F(xiàn)在所有 SDK 都要求在用戶同意隱私政策之后才能初始化提前初始化會(huì)被判定為違規(guī)收集設(shè)備信息。標(biāo)準(zhǔn)做法是在 Application 里先不初始化等用戶在首屏彈窗點(diǎn)同意之后再調(diào)用授權(quán)提交接口并初始化// 用戶點(diǎn)擊同意隱私政策后調(diào)用 MobSDK.submitPolicyGrantResult(true, null);如果你用的是較新的版本這個(gè)方法可能已經(jīng)被整合進(jìn)初始化流程具體以文檔為準(zhǔn)。這個(gè)細(xì)節(jié)不難但它是應(yīng)用上架的硬門檻別放到最后補(bǔ)。3. 初始化、分享調(diào)用與回調(diào)的完整鏈路3.1 初始化時(shí)序什么時(shí)候初始化初始化幾次理想的初始化時(shí)機(jī)是用戶同意隱私政策之后、第一次打開需要分享的頁面之前。也就是放在同意回調(diào)里或者放在 Application 中但用標(biāo)志位控制。初始化本身是冪等的重復(fù)調(diào)用不會(huì)出問題但為了代碼清晰我習(xí)慣用單例包裝一層public class ShareManager { private static volatile boolean inited false; public static void init(Context context) { if (inited) return; synchronized (ShareManager.class) { if (!inited) { MobSDK.submitPolicyGrantResult(true, null); ShareSDK.initSDK(context.getApplicationContext()); inited true; } } } }這里有個(gè)反直覺的點(diǎn)初始化失敗不會(huì)拋異常。ShareSDK 的初始化是異步的失敗信息通過日志輸出客戶端拿不到返回值。所以第一次接入時(shí)一定要開日志開關(guān)把 SDK 內(nèi)部日志打到 LogcatMobSDK.setDebugMode(true); // 僅調(diào)試包打開我見過的問題里有相當(dāng)一部分是AppKey 填錯(cuò)或者AppSecret 少了一位前端表現(xiàn)完全一樣。打開日志后初始化階段的報(bào)錯(cuò)信息會(huì)非常明確能省掉大量猜測(cè)。3.2 平臺(tái)對(duì)象與分享面板兩種調(diào)用姿勢(shì)SDK 提供兩種分享入口各有適用場(chǎng)景。平臺(tái)對(duì)象直調(diào)適合指定渠道、無 UI的場(chǎng)景比如從詳情頁的分享到微信按鈕直接觸發(fā)分享面板適合讓用戶自己選渠道它自帶一套底部彈出的網(wǎng)格 UI你可以自定義標(biāo)題、渠道順序、是否顯示更多。平臺(tái)直調(diào)的核心代碼Platform platform ShareSDK.getPlatform(Wechat.NAME); platform.setPlatformActionListener(new PlatformActionListener() { Override public void onComplete(Platform platform, int action, HashMapString, Object res) { // 分享成功 } Override public void onError(Platform platform, int action, int code, Throwable throwable) { // 分享失敗code 是渠道返回的錯(cuò)誤碼 } Override public void onCancel(Platform platform, int action) { // 用戶取消 } }); Platform.ShareParams params new Platform.ShareParams(); params.setShareType(Platform.SHARE_WEBPAGE); params.setTitle(標(biāo)題文案); params.setText(正文描述); params.setImageUrl(https://你的域名/thumb.png); params.setUrl(https://你的域名/detail?id123); platform.share(params);注意setShareType這個(gè)參數(shù)它決定了分享內(nèi)容被如何解釋。SHARE_WEBPAGE是鏈接卡片SHARE_IMAGE是純圖片SHARE_TEXT是純文本。不同類型支持的字段不同比如純文本類型你設(shè)了 imageUrl 也不會(huì)生效鏈接類型如果不給 url 在微信側(cè)會(huì)直接被拒。這一點(diǎn)務(wù)必對(duì)著渠道能力表核對(duì)。分享面板的寫法更簡(jiǎn)單配置一次 UI 就能復(fù)用OnekeyShare oks new OnekeyShare(); oks.setTitle(分享標(biāo)題); oks.setText(分享正文); oks.setTitleUrl(https://你的域名/detail?id123); oks.setUrl(https://你的域名/detail?id123); oks.setImageUrl(https://你的域名/thumb.png); oks.setSite(你的應(yīng)用名); oks.setSiteUrl(https://你的域名); oks.setCallback(new PlatformActionListener() { /* 同上 */ }); oks.show(context);如果只想顯示部分渠道用oks.setPlatform(...)或者在渠道配置里關(guān)掉不需要的項(xiàng)。定制外觀的部分比如只顯示一行、去掉更多通過OnekeyShareTheme實(shí)現(xiàn)一般項(xiàng)目用默認(rèn)風(fēng)格就夠了不必過度定制。3.3 三種典型內(nèi)容的完整參數(shù)與規(guī)格純文本分享最省事但要注意微信好友對(duì)純文本的支持僅限于會(huì)話朋友圈不支持純文本。文本里帶鏈接時(shí)部分渠道會(huì)自動(dòng)抓取網(wǎng)頁標(biāo)題和縮略圖抓不到就顯示純文本視覺上很樸素。圖文鏈接分享是內(nèi)容類 App 的主力場(chǎng)景參數(shù)上有幾個(gè)硬性要求鏈接必須是公網(wǎng)可訪問的 HTTPS 地址不能是內(nèi)網(wǎng)或本地文件路徑縮略圖必須是公網(wǎng)可訪問的圖片地址不能傳本地路徑。我踩過的坑是測(cè)試環(huán)境用的是內(nèi)網(wǎng)域名本地調(diào)試一切正常線上切了域名反而忘記同步改配置導(dǎo)致縮略圖 404卡片變成灰塊。本地圖片分享適合生成海報(bào)再分享的場(chǎng)景。用setImagePath傳本地絕對(duì)路徑但要注意圖片大小多數(shù)渠道對(duì)分享圖片有上限常見是幾 MB 級(jí)別超過會(huì)被壓縮甚至直接失敗。穩(wěn)妥做法是分享前先自己壓縮一遍private String compressForShare(Bitmap src) { File out new File(context.getCacheDir(), share_ System.currentTimeMillis() .jpg); int maxSide 1080; float scale Math.min(1f, maxSide * 1f / Math.max(src.getWidth(), src.getHeight())); Bitmap scaled Bitmap.createScaledBitmap(src, (int) (src.getWidth() * scale), (int) (src.getHeight() * scale), true); try (FileOutputStream fos new FileOutputStream(out)) { scaled.compress(Bitmap.CompressFormat.JPEG, 85, fos); } catch (IOException e) { return null; } finally { if (scaled ! src) scaled.recycle(); } return out.getAbsolutePath(); }縮略圖規(guī)格是另一個(gè)高頻坑點(diǎn)。微信側(cè)的縮略圖有比較嚴(yán)格的大小限制經(jīng)驗(yàn)值在 32KB 以內(nèi)比較穩(wěn)超過這個(gè)體積可能導(dǎo)致分享卡片顯示異?；蛘咧苯邮?。我的做法是縮略圖單獨(dú)出一張 200x200 左右的小圖別直接復(fù)用列表頁的大圖。3.4 回調(diào)里該做什么、不該做什么回調(diào)是分享鏈路里業(yè)務(wù)價(jià)值最高的部分但也是最容易被寫壞的部分。onComplete里可以做的是記錄埋點(diǎn)、發(fā)放獎(jiǎng)勵(lì)、刷新狀態(tài)。不該做的是彈 Toast 說分享成功——因?yàn)閛nComplete只代表 SDK 層面認(rèn)為分享流程走完了并不等于用戶真的發(fā)到了好友或者朋友圈。部分渠道存在用戶點(diǎn)了發(fā)送但最終取消的情況SDK 無法感知。所以涉及利益的設(shè)計(jì)比如分享得積分我通常做兩層SDK 回調(diào)作為觸發(fā)服務(wù)端做校驗(yàn)。校驗(yàn)方式是記錄分享發(fā)起時(shí)間、渠道、用戶 ID配合頻次限制和風(fēng)控規(guī)則而不是純信任客戶端回調(diào)。這套設(shè)計(jì)做下來惡意刷分的成本會(huì)高很多。onError里的 code 值值得關(guān)注把它落到日志里出問題時(shí)能快速定位是渠道拒絕還是網(wǎng)絡(luò)問題。onCancel建議只做日志不要彈任何提示用戶主動(dòng)取消還彈個(gè)分享取消是很煩人的交互。3.5 分享成功與否的判斷邊界這里得說句實(shí)話沒有哪個(gè)聚合方案能 100% 確認(rèn)用戶真的完成了分享。渠道返回的成功只代表內(nèi)容已成功交給目標(biāo)應(yīng)用用戶可能發(fā)出去也可能在最后一屏取消。能拿到的最強(qiáng)信號(hào)是微信分享后返回的 transaction 標(biāo)識(shí)但即便如此也存在邊界情況。實(shí)踐中的做法是不追求絕對(duì)準(zhǔn)確但要控制損失。具體是本地回調(diào)立即給一個(gè)輕量的 UI 反饋比如按鈕變成已分享服務(wù)端按日限制獎(jiǎng)勵(lì)次數(shù)同時(shí)對(duì)異常高頻賬號(hào)做冷卻。這個(gè)組合能把薅羊毛的收益壓到接近零又不會(huì)誤傷正常用戶。4. 踩坑排查實(shí)錄五類高頻故障的定位路徑4.1 面板彈出來了但渠道是灰的或者點(diǎn)了沒反應(yīng)這是最高頻的問題原因基本集中在三個(gè)地方。第一是包可見性沒聲明Android 11 之后應(yīng)用默認(rèn)看不到其他應(yīng)用SDK 判斷微信未安裝渠道就被置灰。第二是簽名指紋不匹配渠道側(cè)拒絕但不給明確錯(cuò)誤。第三是AppKey 與包名不對(duì)應(yīng)比如測(cè)試包和正式包用了同一份配置但只有正式包在開放平臺(tái)注冊(cè)過。排查順序建議先看 Logcat 里 SDK 的初始化日志確認(rèn)渠道配置是否加載成功再用adb shell pm list packages | grep tencent確認(rèn)設(shè)備上裝了目標(biāo)應(yīng)用然后打印當(dāng)前簽名的 MD5和開放平臺(tái)后臺(tái)逐個(gè)字符對(duì)比最后確認(rèn) AppKey 屬于哪個(gè)包名。4.2 分享出去了但回調(diào)永遠(yuǎn)不回來回調(diào)鏈路涉及你的應(yīng)用 → 目標(biāo)應(yīng)用 → 你的回調(diào) Activity任何一環(huán)斷了都會(huì)表現(xiàn)為分享成功但沒回調(diào)。最常見的原因是WXEntryActivity 的包路徑或類名寫錯(cuò)必須是包名.wxapi.WXEntryActivity且必須繼承 SDK 提供的父類。其次是exported屬性沒開系統(tǒng)不允許外部喚起。第三是清單合并時(shí)被覆蓋比如主模塊和某個(gè)庫都聲明了同名 Activity。我建議在集成完成后立刻做一次回調(diào)自測(cè)隨便分享一條文本看 Logcat 里有沒有進(jìn)入回調(diào)類。如果沒有任何日志基本可以確定是清單或類路徑問題而不是代碼邏輯問題。4.3 Debug 正常Release 包分享必失敗這類只在線上出現(xiàn)的問題八成是混淆或者簽名差異。混淆方面除了前面提到的 keep 規(guī)則還要注意某些渠道 SDK 用了反射調(diào)用自己的內(nèi)部類規(guī)則里統(tǒng)一用通配符保留整個(gè)包最穩(wěn)。簽名方面很多團(tuán)隊(duì)本地調(diào)試用 debug 簽名CI 出包用 release 簽名但開放平臺(tái)上只注冊(cè)了其中一個(gè)。這時(shí)候的表現(xiàn)是本地測(cè)試全綠打包給別人裝就廢。我的做法是在構(gòu)建腳本里加一道檢查打包時(shí)打印當(dāng)前簽名指紋和文檔里記錄的正式簽名做人工核對(duì)。這個(gè)動(dòng)作花不了一分鐘能擋住很多低級(jí)問題。4.4 圖片分享失敗、內(nèi)存溢出與白屏圖片相關(guān)的問題集中在體積和格式。體積上超過渠道限制會(huì)被拒格式上部分渠道不接受 WebP建議統(tǒng)一轉(zhuǎn) JPEG。內(nèi)存上從相冊(cè)取原圖直接分享在低端機(jī)上很容易 OOM尤其是 4000 萬像素的照片。處理思路是進(jìn)內(nèi)存之前先降采樣。用BitmapFactory.Options的inJustDecodeBounds先讀尺寸算出采樣率再真正解碼這一步能把內(nèi)存占用降到原來的幾分之一。分享用的圖片不需要原圖質(zhì)量1080 長(zhǎng)邊、85 壓縮率在手機(jī)上看起來完全夠用。還有一類白屏問題容易被誤判成崩潰分享鏈接卡片時(shí)如果頁面需要登錄才能訪問渠道抓取時(shí)會(huì)拿到登錄頁卡片顯示空白或者錯(cuò)誤標(biāo)題。解決辦法是給分享鏈接加一個(gè)免登錄的預(yù)覽路徑或者在頁面里補(bǔ) Open Graph 標(biāo)簽title、description、image讓抓取器能拿到正確信息。4.5 常見問題速查表現(xiàn)象最可能的原因快速驗(yàn)證方式渠道置灰不可點(diǎn)未聲明包可見性 / 目標(biāo)應(yīng)用未安裝檢查 queries 聲明adb 查包名點(diǎn)擊后無任何反應(yīng)AppKey 與包名不匹配打開 SDK 調(diào)試日志看初始化結(jié)果分享成功但無回調(diào)wxapi 路徑或 exported 屬性錯(cuò)誤檢查合并后的清單文件僅 Release 包失敗混淆規(guī)則缺失 / 簽名不一致對(duì)比 debug 與 release 的簽名指紋縮略圖不顯示圖片地址非公網(wǎng) / 體積超限瀏覽器直接訪問該 URL看文件大小鏈接卡片標(biāo)題為空頁面缺少抓取標(biāo)簽 / 需登錄用鏈接抓取工具預(yù)覽這張表我一般直接貼在項(xiàng)目 wiki 上新人遇到問題先自查一遍能過濾掉大部分常見情況。5. 上線前的收尾包體、降級(jí)與數(shù)據(jù)回收5.1 按需引入渠道別把整套都打進(jìn)去聚合 SDK 的一個(gè)副作用是包體會(huì)變大因?yàn)樗讯鄠€(gè)渠道的客戶端代碼都塞進(jìn)來了。如果你的產(chǎn)品只需要微信和 QQ就在配置里把微博相關(guān)的項(xiàng)去掉插件會(huì)相應(yīng)地不注入對(duì)應(yīng)模塊。這一步通常能省下幾百 KB 到 1MB 不等對(duì)包體敏感的項(xiàng)目值得做。除了渠道裁剪還可以關(guān)注資源配置的合并。分享面板的圖標(biāo)、多語言字符串都是資源如果項(xiàng)目本身做了資源壓縮記得檢查分享相關(guān)資源有沒有被誤刪。我遇到過一次面板圖標(biāo)全變成方塊最后發(fā)現(xiàn)是資源壓縮規(guī)則里把share*前綴的資源全排除了。5.2 失敗降級(jí)讓用戶永遠(yuǎn)有出口分享失敗最差的體驗(yàn)是什么都沒發(fā)生。我習(xí)慣在失敗回調(diào)里做兩級(jí)降級(jí)第一級(jí)如果是目標(biāo)應(yīng)用未安裝彈一個(gè)提示引導(dǎo)用戶同時(shí)把該渠道在面板里隱藏一段時(shí)間第二級(jí)如果連續(xù)失敗自動(dòng)切到系統(tǒng)分享作為兜底。系統(tǒng)分享雖然拿不到回調(diào)但至少用戶能把內(nèi)容發(fā)出去體驗(yàn)上是部分成功而不是完全失敗。這個(gè)兜底邏輯用 Android 原生的Intent.ACTION_SEND實(shí)現(xiàn)即可不需要額外依賴Intent intent new Intent(Intent.ACTION_SEND); intent.setType(text/plain); intent.putExtra(Intent.EXTRA_TEXT, 正文內(nèi)容 https://你的域名/detail?id123); context.startActivity(Intent.createChooser(intent, 分享到));記得判空resolveActivity否則在沒有可分享應(yīng)用的設(shè)備上會(huì)拋異常。5.3 埋點(diǎn)把分享這件事量化出來分享功能的業(yè)務(wù)價(jià)值需要通過數(shù)據(jù)說話。我一般埋三個(gè)點(diǎn)面板曝光用戶看到了哪些渠道、渠道點(diǎn)擊用戶選了哪個(gè)、結(jié)果回調(diào)成功/失敗/取消帶錯(cuò)誤碼。這三個(gè)點(diǎn)串起來能算出每個(gè)渠道的點(diǎn)擊率、成功率、失敗原因分布。有了這組數(shù)據(jù)很多決策就有依據(jù)了。比如某個(gè)渠道成功率長(zhǎng)期低于 80%先去查是不是版本兼容問題某個(gè)渠道點(diǎn)擊率高但成功率低可能是參數(shù)配置有問題。沒有數(shù)據(jù)的團(tuán)隊(duì)只能靠用戶投訴來發(fā)現(xiàn)問題滯后性好幾天。埋點(diǎn)實(shí)現(xiàn)上有個(gè)細(xì)節(jié)回調(diào)可能在非主線程寫數(shù)據(jù)庫或者上報(bào)要注意線程切換。另外分享面板的曝光時(shí)機(jī)建議放在show()之后延時(shí)一小段避免把面板初始化失敗也算成曝光。5.4 版本升級(jí)的回歸清單SDK 升級(jí)不是換個(gè)版本號(hào)就完事。我整理了一份自己的回歸清單每次升級(jí)按這個(gè)走一遍初始化是否正?？慈罩?、面板是否能彈出、每個(gè)渠道是否都能走通、回調(diào)是否正常觸發(fā)、Release 包混淆后是否正常、低版本 Android尤其是 7.0 和 11是否正常、未安裝目標(biāo)應(yīng)用時(shí)提示是否正確。這七項(xiàng)跑完大概二十分鐘但能避免上線后回滾。我吃過一次虧升級(jí)后功能全對(duì)但忘了驗(yàn)證 Android 11 的包可見性結(jié)果新系統(tǒng)用戶全部無法分享緊急發(fā)版修了兩天才穩(wěn)住。最后分享一個(gè)我自己的習(xí)慣。每次集成或升級(jí)完分享功能我會(huì)在真機(jī)上用三無環(huán)境測(cè)一遍——沒有緩存、沒有登錄、剛裝的包。這個(gè)環(huán)境最接近新用戶很多因?yàn)楸镜貭顟B(tài)殘留而被掩蓋的問題會(huì)立刻暴露出來。踩過幾次坑之后這個(gè)動(dòng)作已經(jīng)變成我的肌肉記憶了。 Android ShareSDK 聚合分享集成與回調(diào)排障指南
上周又有人在群里拋截圖面板彈出來了點(diǎn)微信好友轉(zhuǎn)圈兩秒然后沒下文日志里干干凈凈。這種問題十有八九不是 SDK 壞了是接入鏈路上某個(gè)環(huán)節(jié)對(duì)不上。做過 Android Studio 里集成 ShareSDK 做第三方分享的同學(xué)應(yīng)該都懂聚合分享這活兒看著是引個(gè)依賴、調(diào)個(gè) show實(shí)際上從開放平臺(tái)注冊(cè)、簽名指紋、清單文件、回調(diào) Activity 到混淆規(guī)則至少有五六個(gè)地方要同時(shí)對(duì)齊任何一個(gè)錯(cuò)位表現(xiàn)都是同一個(gè)——分享不出去。這篇東西就是把這些環(huán)節(jié)拆開講清楚。ShareSDK 是一套聚合分享組件把微信、QQ、微博、系統(tǒng)分享這些渠道的登錄、分享、回調(diào)收斂成一套統(tǒng)一 API省掉你逐個(gè)接入原生 SDK 的重復(fù)勞動(dòng)適合需要點(diǎn)多面廣分享能力的中大型 App也適合剛接手老項(xiàng)目、被回調(diào)問題折磨的同學(xué)。下面從選型邏輯一路講到線上收尾能直接抄的部分我盡量寫成可復(fù)制的代碼和配置。1. 先把需求拆干凈為什么選聚合分享 SDK 而不是逐個(gè)接原生1.1 逐個(gè)接原生 SDK 的隱性成本遠(yuǎn)高于第一眼看到的很多人做技術(shù)選型時(shí)算的賬是接三個(gè)平臺(tái)的原生 SDK 大概兩天實(shí)際干下來往往是一周。原因不在核心代碼量而在那些看不到的協(xié)調(diào)成本。每個(gè)渠道都要單獨(dú)去開放平臺(tái)注冊(cè)應(yīng)用、填包名、填簽名、等審核每個(gè)渠道的回調(diào) Activity 放在不同的包里、繼承不同的父類、注冊(cè)不同的 intent-filter每個(gè)渠道的分享參數(shù)結(jié)構(gòu)還各不相同——圖片鏈接在 A 平臺(tái)叫 imageUrl在 B 平臺(tái)叫 imageObject壓縮策略和尺寸上限也不一樣。更要命的是這些代碼會(huì)隨平臺(tái)更新而失效。某個(gè)平臺(tái)某次調(diào)整了縮略圖上限你的分享就靜默失敗某個(gè)平臺(tái)把回調(diào)類的包名規(guī)則收緊你的分享成功但 UI 永遠(yuǎn)停在分享中。三套代碼意味著三次回歸測(cè)試四套就是四次。如果產(chǎn)品需求只是能讓用戶把內(nèi)容發(fā)出去這筆投入的性價(jià)比非常低。我見過一個(gè)內(nèi)容類項(xiàng)目最初老老實(shí)實(shí)接了三個(gè)原生 SDK后來產(chǎn)品要加兩個(gè)新渠道評(píng)估下來改動(dòng)量比重新接一遍還大最后整體換成了聚合方案。所以選型時(shí)真正該問的不是聚合 SDK 是不是更輕而是我要維護(hù)的渠道數(shù)量會(huì)不會(huì)變。只要答案是會(huì)聚合方案的優(yōu)勢(shì)就成立。1.2 聚合方案幫你抹平了什么又沒有幫你抹平什么ShareSDK 的核心價(jià)值是把渠道差異收進(jìn) SDK 內(nèi)部對(duì)外只暴露一層統(tǒng)一接口統(tǒng)一初始化、統(tǒng)一平臺(tái)標(biāo)識(shí)、統(tǒng)一分享參數(shù)結(jié)構(gòu)、統(tǒng)一回調(diào)協(xié)議、統(tǒng)一分享面板 UI。你在業(yè)務(wù)層寫一份代碼切換渠道只是換一個(gè)字符串常量。這對(duì)業(yè)務(wù)層是實(shí)打?qū)嵉臏p負(fù)尤其是分享面板這種交互統(tǒng)一、業(yè)務(wù)邏輯薄的功能。但它不是銀彈有幾件事它替你做不了開放平臺(tái)的應(yīng)用注冊(cè)與審核是你自己的賬號(hào)行為包名與簽名的綁定關(guān)系必須你手動(dòng)填對(duì)SDK 沒法猜目標(biāo) App 未安裝時(shí)的降級(jí)體驗(yàn)需要你在業(yè)務(wù)層設(shè)計(jì)圖片資源合規(guī)尺寸、格式、是否公網(wǎng)可訪問依然是調(diào)用方責(zé)任。把這四件事當(dāng)成SDK 應(yīng)該自動(dòng)處理的基本都會(huì)在調(diào)試階段撞墻。理解這一點(diǎn)很重要因?yàn)樗鼪Q定了你的調(diào)試順序。當(dāng)你遇到分享沒反應(yīng)第一反應(yīng)不應(yīng)該是去翻 SDK 源碼而應(yīng)該按賬號(hào)綁定 → 清單文件 → 回調(diào)注冊(cè) → 參數(shù)合法這條鏈路逐段卡點(diǎn)。后面第 4 章的排查表就是按這個(gè)順序排的。1.3 渠道能力矩陣先想清楚哪些渠道真的需要不同渠道的能力差異很大不是所有渠道都值得接。接之前先拿一張表把需求框住能省掉一半工作量。下表是基于常見實(shí)踐的整理具體以你接入時(shí)服務(wù)方文檔為準(zhǔn)渠道是否需要開放平臺(tái)審核是否要求客戶端安裝回調(diào)機(jī)制常見坑點(diǎn)微信好友是需應(yīng)用審核通過是通過 wxapi 包下的回調(diào)類包名/簽名不匹配直接無回調(diào)微信朋友圈是是同上僅支持圖文/鏈接純文本受限QQ / Qzone是是SDK 內(nèi)部廣播 回調(diào)類tencentappId 的 scheme 未聲明微博是是回調(diào)類圖片需先上傳鏈接需備案域名系統(tǒng)分享否否無回調(diào)只能拿到已喚起拿不到結(jié)果這張表最關(guān)鍵的信息其實(shí)是最后一列——只有系統(tǒng)分享是無回調(diào)的其余渠道理論上都能拿到成功/失敗/取消三態(tài)。如果你的產(chǎn)品經(jīng)理要求分享成功給積分那就必須走前四類系統(tǒng)分享只能算兜底入口。另外還要注意一個(gè)產(chǎn)品側(cè)的取舍微信朋友圈對(duì)純文本分享有限制如果你要分享的是純文字內(nèi)容朋友圈渠道實(shí)際上會(huì)失敗需要在 UI 上把該渠道置灰或者自動(dòng)轉(zhuǎn)成生成圖片再分享。這類細(xì)節(jié)在需求評(píng)審階段就該確認(rèn)別等聯(lián)調(diào)時(shí)才發(fā)現(xiàn)。1.4 版本矩陣SDK、構(gòu)建插件、AGP 三者必須對(duì)齊這里單獨(dú)拎出來講因?yàn)樗切率肿钊菀缀雎?、也最容易?dǎo)致編譯過了但運(yùn)行崩的原因。聚合 SDK 通常以 Gradle 插件形式接入負(fù)責(zé)自動(dòng)注入清單、自動(dòng)生成渠道配置這個(gè)插件對(duì) Android Gradle Plugin 的版本是有要求的。AGP 升級(jí)到較新版本后老插件可能無法解析變體信息表現(xiàn)為構(gòu)建期報(bào)找不到 task 或者清單合并失敗。我的建議是把三個(gè)版本號(hào)寫進(jìn)項(xiàng)目文檔并鎖死AGP 版本、Gradle Wrapper 版本、分享 SDK 插件版本。升級(jí) AGP 時(shí)把這三個(gè)一起評(píng)估別單獨(dú)動(dòng)一個(gè)。如果確實(shí)要升級(jí)先在獨(dú)立分支上升跑通初始化 → 分享 → 回調(diào)完整鏈路再合回主干。這個(gè)流程聽起來啰嗦但比線上發(fā)現(xiàn)問題強(qiáng)太多。2. 動(dòng)手之前的三件事賬號(hào)、簽名、工程基線2.1 包名與簽名指紋是繞不過去的硬門檻所有渠道的審核第一步都是你是誰。開放平臺(tái)通過應(yīng)用包名 簽名指紋來識(shí)別調(diào)用方兩者任一不匹配渠道側(cè)會(huì)直接拒絕而客戶端往往拿不到明確錯(cuò)誤只表現(xiàn)為點(diǎn)了沒反應(yīng)。所以這一步必須先做且要用正式發(fā)布用的簽名文件去算指紋不要用 debug 簽名湊數(shù)。取指紋有兩條路。第一條是命令行直接讀 keystorekeytool -list -v \ -keystore release.jks \ -alias your_alias \ -storepass 你的store密碼 \ -keypass 你的key密碼輸出里會(huì)有一行MD5:和一串冒號(hào)分隔的十六進(jìn)制。第二條是 Gradle 自帶的報(bào)告任務(wù)在 Android Studio 的 Terminal 里執(zhí)行./gradlew signingReport它會(huì)把每個(gè)變體用的簽名信息都打出來包括 MD5 和 SHA1很適合確認(rèn)當(dāng)前構(gòu)建到底簽的哪個(gè)文件。我用這條命令查出過一次事故CI 上配置的 keystore 路徑寫錯(cuò)回退到了默認(rèn) debug 簽名本地調(diào)試一切正常出包就全渠道失效。關(guān)于格式這里有個(gè)特別容易被卡住的細(xì)節(jié)不同渠道對(duì)指紋格式要求不一樣。有的要小寫無冒號(hào)有的要大寫帶冒號(hào)有的要 SHA1。填之前把平臺(tái)頁面的輸入框提示看清楚實(shí)在不確定就把大小寫兩種都試一遍。我習(xí)慣在文檔里存一份對(duì)照表包含每個(gè)渠道填的字段、格式、填寫日期換人接手時(shí)不用重新考古。2.2 Gradle 倉庫與插件配置的寫法工程基線部分分三步加倉庫、加插件依賴、加渠道配置。倉庫地址會(huì)隨服務(wù)方調(diào)整而變化我不建議在文章里貼死鏈按你接入時(shí)的官方文檔填即可通常形如// 項(xiàng)目根目錄 build.gradle buildscript { repositories { google() mavenCentral() maven { url SDK服務(wù)方提供的Maven倉庫地址 } // 以官方文檔為準(zhǔn) } dependencies { classpath com.android.tools.build:gradle:8.x.x classpath SDK服務(wù)方提供的構(gòu)建插件坐標(biāo) // 與SDK大版本對(duì)應(yīng) } } allprojects { repositories { google() mavenCentral() maven { url SDK服務(wù)方提供的Maven倉庫地址 } } }然后在 app 模塊里應(yīng)用插件并填寫渠道信息// app/build.gradle apply plugin: com.android.application apply plugin: SDK服務(wù)方提供的插件名 SDK配置塊 { appKey 你的AppKey appSecret 你的AppSecret ShareSDK { devInfo { Wechat { appId wx開頭的AppID appSecret 微信開放平臺(tái)的應(yīng)用密鑰 withShareTicket true bypassApproval false } WechatMoments { appId 同一個(gè)AppID appSecret 同一個(gè)密鑰 bypassApproval false } QQ { appId QQ互聯(lián)的數(shù)字AppID appKey QQ互聯(lián)的AppKey } SinaWeibo { appKey 微博的AppKey appSecret 微博的AppSecret callbackUri https://你的回調(diào)地址 shareByAppClient true } } } }這段配置的本質(zhì)是在編譯期生成渠道清單和初始化參數(shù)所以改完必須重新構(gòu)建光改代碼不重新 sync 是不生效的。我遇到過同事改完配置直接點(diǎn)運(yùn)行結(jié)果用的還是緩存里的舊清單排查了半小時(shí)。養(yǎng)成習(xí)慣改了這段就 Clean 一次。2.3 清單文件幾個(gè)必須手寫的聲明雖然插件會(huì)自動(dòng)注入大部分內(nèi)容但有兩處必須自己寫清楚。第一處是微信回調(diào) Activity它必須放在你的包名.wxapi這個(gè)固定路徑下類名必須是WXEntryActivity少一個(gè)字都收不到回調(diào)package com.example.demo.wxapi; import cn.sharesdk.wechat.utils.WXEntryActivity; public class WXEntryActivity extends WXEntryActivity { // 不需要寫任何代碼父類已經(jīng)處理了回調(diào)分發(fā) }對(duì)應(yīng)清單聲明activity android:name.wxapi.WXEntryActivity android:exportedtrue android:launchModesingleTop android:taskAffinity你的包名 android:themeandroid:style/Theme.Translucent.NoTitleBar /exportedtrue是必須的因?yàn)榛卣{(diào)是從外部應(yīng)用喚起的taskAffinity設(shè)成包名是為了避免多任務(wù)棧里出現(xiàn)重復(fù)頁面。第二處是Android 11 及以上的包可見性聲明不加的話你連微信是否安裝都判斷不出來渠道會(huì)一直顯示為不可用queries package android:namecom.tencent.mm / package android:namecom.tencent.mobileqq / intent action android:nameandroid.intent.action.VIEW / data android:schemeweixin / /intent /queriesQQ 的回調(diào)還需要在清單里聲明tencent加 AppID 的 scheme這個(gè)通常由插件生成但如果你手動(dòng)裁剪過清單記得檢查一遍。我一般會(huì)在集成完成后做一次清單體檢把合并后的清單導(dǎo)出來搜索wxapi、tencent、queries三個(gè)關(guān)鍵字確認(rèn)都在。2.4 混淆規(guī)則和隱私初始化時(shí)機(jī)混淆這塊的規(guī)則不復(fù)雜但漏了就是線上崩潰且往往在灰度階段才發(fā)現(xiàn)-keep class cn.sharesdk.** { *; } -keep class com.mob.** { *; } -keep class com.sina.** { *; } -keep class **.R$* { *; } -keep class **.wxapi.** { *; } -dontwarn cn.sharesdk.** -dontwarn com.mob.**注意最后那條**.wxapi.**很多人只保留了 SDK 包名忘了自己的回調(diào)類也在反射調(diào)用鏈上混淆后類名變了回調(diào)自然分發(fā)不到。另一個(gè)必須提的是隱私合規(guī)?，F(xiàn)在所有 SDK 都要求在用戶同意隱私政策之后才能初始化提前初始化會(huì)被判定為違規(guī)收集設(shè)備信息。標(biāo)準(zhǔn)做法是在 Application 里先不初始化等用戶在首屏彈窗點(diǎn)同意之后再調(diào)用授權(quán)提交接口并初始化// 用戶點(diǎn)擊同意隱私政策后調(diào)用 MobSDK.submitPolicyGrantResult(true, null);如果你用的是較新的版本這個(gè)方法可能已經(jīng)被整合進(jìn)初始化流程具體以文檔為準(zhǔn)。這個(gè)細(xì)節(jié)不難但它是應(yīng)用上架的硬門檻別放到最后補(bǔ)。3. 初始化、分享調(diào)用與回調(diào)的完整鏈路3.1 初始化時(shí)序什么時(shí)候初始化初始化幾次理想的初始化時(shí)機(jī)是用戶同意隱私政策之后、第一次打開需要分享的頁面之前。也就是放在同意回調(diào)里或者放在 Application 中但用標(biāo)志位控制。初始化本身是冪等的重復(fù)調(diào)用不會(huì)出問題但為了代碼清晰我習(xí)慣用單例包裝一層public class ShareManager { private static volatile boolean inited false; public static void init(Context context) { if (inited) return; synchronized (ShareManager.class) { if (!inited) { MobSDK.submitPolicyGrantResult(true, null); ShareSDK.initSDK(context.getApplicationContext()); inited true; } } } }這里有個(gè)反直覺的點(diǎn)初始化失敗不會(huì)拋異常。ShareSDK 的初始化是異步的失敗信息通過日志輸出客戶端拿不到返回值。所以第一次接入時(shí)一定要開日志開關(guān)把 SDK 內(nèi)部日志打到 LogcatMobSDK.setDebugMode(true); // 僅調(diào)試包打開我見過的問題里有相當(dāng)一部分是AppKey 填錯(cuò)或者AppSecret 少了一位前端表現(xiàn)完全一樣。打開日志后初始化階段的報(bào)錯(cuò)信息會(huì)非常明確能省掉大量猜測(cè)。3.2 平臺(tái)對(duì)象與分享面板兩種調(diào)用姿勢(shì)SDK 提供兩種分享入口各有適用場(chǎng)景。平臺(tái)對(duì)象直調(diào)適合指定渠道、無 UI的場(chǎng)景比如從詳情頁的分享到微信按鈕直接觸發(fā)分享面板適合讓用戶自己選渠道它自帶一套底部彈出的網(wǎng)格 UI你可以自定義標(biāo)題、渠道順序、是否顯示更多。平臺(tái)直調(diào)的核心代碼Platform platform ShareSDK.getPlatform(Wechat.NAME); platform.setPlatformActionListener(new PlatformActionListener() { Override public void onComplete(Platform platform, int action, HashMapString, Object res) { // 分享成功 } Override public void onError(Platform platform, int action, int code, Throwable throwable) { // 分享失敗code 是渠道返回的錯(cuò)誤碼 } Override public void onCancel(Platform platform, int action) { // 用戶取消 } }); Platform.ShareParams params new Platform.ShareParams(); params.setShareType(Platform.SHARE_WEBPAGE); params.setTitle(標(biāo)題文案); params.setText(正文描述); params.setImageUrl(https://你的域名/thumb.png); params.setUrl(https://你的域名/detail?id123); platform.share(params);注意setShareType這個(gè)參數(shù)它決定了分享內(nèi)容被如何解釋。SHARE_WEBPAGE是鏈接卡片SHARE_IMAGE是純圖片SHARE_TEXT是純文本。不同類型支持的字段不同比如純文本類型你設(shè)了 imageUrl 也不會(huì)生效鏈接類型如果不給 url 在微信側(cè)會(huì)直接被拒。這一點(diǎn)務(wù)必對(duì)著渠道能力表核對(duì)。分享面板的寫法更簡(jiǎn)單配置一次 UI 就能復(fù)用OnekeyShare oks new OnekeyShare(); oks.setTitle(分享標(biāo)題); oks.setText(分享正文); oks.setTitleUrl(https://你的域名/detail?id123); oks.setUrl(https://你的域名/detail?id123); oks.setImageUrl(https://你的域名/thumb.png); oks.setSite(你的應(yīng)用名); oks.setSiteUrl(https://你的域名); oks.setCallback(new PlatformActionListener() { /* 同上 */ }); oks.show(context);如果只想顯示部分渠道用oks.setPlatform(...)或者在渠道配置里關(guān)掉不需要的項(xiàng)。定制外觀的部分比如只顯示一行、去掉更多通過OnekeyShareTheme實(shí)現(xiàn)一般項(xiàng)目用默認(rèn)風(fēng)格就夠了不必過度定制。3.3 三種典型內(nèi)容的完整參數(shù)與規(guī)格純文本分享最省事但要注意微信好友對(duì)純文本的支持僅限于會(huì)話朋友圈不支持純文本。文本里帶鏈接時(shí)部分渠道會(huì)自動(dòng)抓取網(wǎng)頁標(biāo)題和縮略圖抓不到就顯示純文本視覺上很樸素。圖文鏈接分享是內(nèi)容類 App 的主力場(chǎng)景參數(shù)上有幾個(gè)硬性要求鏈接必須是公網(wǎng)可訪問的 HTTPS 地址不能是內(nèi)網(wǎng)或本地文件路徑縮略圖必須是公網(wǎng)可訪問的圖片地址不能傳本地路徑。我踩過的坑是測(cè)試環(huán)境用的是內(nèi)網(wǎng)域名本地調(diào)試一切正常線上切了域名反而忘記同步改配置導(dǎo)致縮略圖 404卡片變成灰塊。本地圖片分享適合生成海報(bào)再分享的場(chǎng)景。用setImagePath傳本地絕對(duì)路徑但要注意圖片大小多數(shù)渠道對(duì)分享圖片有上限常見是幾 MB 級(jí)別超過會(huì)被壓縮甚至直接失敗。穩(wěn)妥做法是分享前先自己壓縮一遍private String compressForShare(Bitmap src) { File out new File(context.getCacheDir(), share_ System.currentTimeMillis() .jpg); int maxSide 1080; float scale Math.min(1f, maxSide * 1f / Math.max(src.getWidth(), src.getHeight())); Bitmap scaled Bitmap.createScaledBitmap(src, (int) (src.getWidth() * scale), (int) (src.getHeight() * scale), true); try (FileOutputStream fos new FileOutputStream(out)) { scaled.compress(Bitmap.CompressFormat.JPEG, 85, fos); } catch (IOException e) { return null; } finally { if (scaled ! src) scaled.recycle(); } return out.getAbsolutePath(); }縮略圖規(guī)格是另一個(gè)高頻坑點(diǎn)。微信側(cè)的縮略圖有比較嚴(yán)格的大小限制經(jīng)驗(yàn)值在 32KB 以內(nèi)比較穩(wěn)超過這個(gè)體積可能導(dǎo)致分享卡片顯示異?；蛘咧苯邮?。我的做法是縮略圖單獨(dú)出一張 200x200 左右的小圖別直接復(fù)用列表頁的大圖。3.4 回調(diào)里該做什么、不該做什么回調(diào)是分享鏈路里業(yè)務(wù)價(jià)值最高的部分但也是最容易被寫壞的部分。onComplete里可以做的是記錄埋點(diǎn)、發(fā)放獎(jiǎng)勵(lì)、刷新狀態(tài)。不該做的是彈 Toast 說分享成功——因?yàn)閛nComplete只代表 SDK 層面認(rèn)為分享流程走完了并不等于用戶真的發(fā)到了好友或者朋友圈。部分渠道存在用戶點(diǎn)了發(fā)送但最終取消的情況SDK 無法感知。所以涉及利益的設(shè)計(jì)比如分享得積分我通常做兩層SDK 回調(diào)作為觸發(fā)服務(wù)端做校驗(yàn)。校驗(yàn)方式是記錄分享發(fā)起時(shí)間、渠道、用戶 ID配合頻次限制和風(fēng)控規(guī)則而不是純信任客戶端回調(diào)。這套設(shè)計(jì)做下來惡意刷分的成本會(huì)高很多。onError里的 code 值值得關(guān)注把它落到日志里出問題時(shí)能快速定位是渠道拒絕還是網(wǎng)絡(luò)問題。onCancel建議只做日志不要彈任何提示用戶主動(dòng)取消還彈個(gè)分享取消是很煩人的交互。3.5 分享成功與否的判斷邊界這里得說句實(shí)話沒有哪個(gè)聚合方案能 100% 確認(rèn)用戶真的完成了分享。渠道返回的成功只代表內(nèi)容已成功交給目標(biāo)應(yīng)用用戶可能發(fā)出去也可能在最后一屏取消。能拿到的最強(qiáng)信號(hào)是微信分享后返回的 transaction 標(biāo)識(shí)但即便如此也存在邊界情況。實(shí)踐中的做法是不追求絕對(duì)準(zhǔn)確但要控制損失。具體是本地回調(diào)立即給一個(gè)輕量的 UI 反饋比如按鈕變成已分享服務(wù)端按日限制獎(jiǎng)勵(lì)次數(shù)同時(shí)對(duì)異常高頻賬號(hào)做冷卻。這個(gè)組合能把薅羊毛的收益壓到接近零又不會(huì)誤傷正常用戶。4. 踩坑排查實(shí)錄五類高頻故障的定位路徑4.1 面板彈出來了但渠道是灰的或者點(diǎn)了沒反應(yīng)這是最高頻的問題原因基本集中在三個(gè)地方。第一是包可見性沒聲明Android 11 之后應(yīng)用默認(rèn)看不到其他應(yīng)用SDK 判斷微信未安裝渠道就被置灰。第二是簽名指紋不匹配渠道側(cè)拒絕但不給明確錯(cuò)誤。第三是AppKey 與包名不對(duì)應(yīng)比如測(cè)試包和正式包用了同一份配置但只有正式包在開放平臺(tái)注冊(cè)過。排查順序建議先看 Logcat 里 SDK 的初始化日志確認(rèn)渠道配置是否加載成功再用adb shell pm list packages | grep tencent確認(rèn)設(shè)備上裝了目標(biāo)應(yīng)用然后打印當(dāng)前簽名的 MD5和開放平臺(tái)后臺(tái)逐個(gè)字符對(duì)比最后確認(rèn) AppKey 屬于哪個(gè)包名。4.2 分享出去了但回調(diào)永遠(yuǎn)不回來回調(diào)鏈路涉及你的應(yīng)用 → 目標(biāo)應(yīng)用 → 你的回調(diào) Activity任何一環(huán)斷了都會(huì)表現(xiàn)為分享成功但沒回調(diào)。最常見的原因是WXEntryActivity 的包路徑或類名寫錯(cuò)必須是包名.wxapi.WXEntryActivity且必須繼承 SDK 提供的父類。其次是exported屬性沒開系統(tǒng)不允許外部喚起。第三是清單合并時(shí)被覆蓋比如主模塊和某個(gè)庫都聲明了同名 Activity。我建議在集成完成后立刻做一次回調(diào)自測(cè)隨便分享一條文本看 Logcat 里有沒有進(jìn)入回調(diào)類。如果沒有任何日志基本可以確定是清單或類路徑問題而不是代碼邏輯問題。4.3 Debug 正常Release 包分享必失敗這類只在線上出現(xiàn)的問題八成是混淆或者簽名差異。混淆方面除了前面提到的 keep 規(guī)則還要注意某些渠道 SDK 用了反射調(diào)用自己的內(nèi)部類規(guī)則里統(tǒng)一用通配符保留整個(gè)包最穩(wěn)。簽名方面很多團(tuán)隊(duì)本地調(diào)試用 debug 簽名CI 出包用 release 簽名但開放平臺(tái)上只注冊(cè)了其中一個(gè)。這時(shí)候的表現(xiàn)是本地測(cè)試全綠打包給別人裝就廢。我的做法是在構(gòu)建腳本里加一道檢查打包時(shí)打印當(dāng)前簽名指紋和文檔里記錄的正式簽名做人工核對(duì)。這個(gè)動(dòng)作花不了一分鐘能擋住很多低級(jí)問題。4.4 圖片分享失敗、內(nèi)存溢出與白屏圖片相關(guān)的問題集中在體積和格式。體積上超過渠道限制會(huì)被拒格式上部分渠道不接受 WebP建議統(tǒng)一轉(zhuǎn) JPEG。內(nèi)存上從相冊(cè)取原圖直接分享在低端機(jī)上很容易 OOM尤其是 4000 萬像素的照片。處理思路是進(jìn)內(nèi)存之前先降采樣。用BitmapFactory.Options的inJustDecodeBounds先讀尺寸算出采樣率再真正解碼這一步能把內(nèi)存占用降到原來的幾分之一。分享用的圖片不需要原圖質(zhì)量1080 長(zhǎng)邊、85 壓縮率在手機(jī)上看起來完全夠用。還有一類白屏問題容易被誤判成崩潰分享鏈接卡片時(shí)如果頁面需要登錄才能訪問渠道抓取時(shí)會(huì)拿到登錄頁卡片顯示空白或者錯(cuò)誤標(biāo)題。解決辦法是給分享鏈接加一個(gè)免登錄的預(yù)覽路徑或者在頁面里補(bǔ) Open Graph 標(biāo)簽title、description、image讓抓取器能拿到正確信息。4.5 常見問題速查表現(xiàn)象最可能的原因快速驗(yàn)證方式渠道置灰不可點(diǎn)未聲明包可見性 / 目標(biāo)應(yīng)用未安裝檢查 queries 聲明adb 查包名點(diǎn)擊后無任何反應(yīng)AppKey 與包名不匹配打開 SDK 調(diào)試日志看初始化結(jié)果分享成功但無回調(diào)wxapi 路徑或 exported 屬性錯(cuò)誤檢查合并后的清單文件僅 Release 包失敗混淆規(guī)則缺失 / 簽名不一致對(duì)比 debug 與 release 的簽名指紋縮略圖不顯示圖片地址非公網(wǎng) / 體積超限瀏覽器直接訪問該 URL看文件大小鏈接卡片標(biāo)題為空頁面缺少抓取標(biāo)簽 / 需登錄用鏈接抓取工具預(yù)覽這張表我一般直接貼在項(xiàng)目 wiki 上新人遇到問題先自查一遍能過濾掉大部分常見情況。5. 上線前的收尾包體、降級(jí)與數(shù)據(jù)回收5.1 按需引入渠道別把整套都打進(jìn)去聚合 SDK 的一個(gè)副作用是包體會(huì)變大因?yàn)樗讯鄠€(gè)渠道的客戶端代碼都塞進(jìn)來了。如果你的產(chǎn)品只需要微信和 QQ就在配置里把微博相關(guān)的項(xiàng)去掉插件會(huì)相應(yīng)地不注入對(duì)應(yīng)模塊。這一步通常能省下幾百 KB 到 1MB 不等對(duì)包體敏感的項(xiàng)目值得做。除了渠道裁剪還可以關(guān)注資源配置的合并。分享面板的圖標(biāo)、多語言字符串都是資源如果項(xiàng)目本身做了資源壓縮記得檢查分享相關(guān)資源有沒有被誤刪。我遇到過一次面板圖標(biāo)全變成方塊最后發(fā)現(xiàn)是資源壓縮規(guī)則里把share*前綴的資源全排除了。5.2 失敗降級(jí)讓用戶永遠(yuǎn)有出口分享失敗最差的體驗(yàn)是什么都沒發(fā)生。我習(xí)慣在失敗回調(diào)里做兩級(jí)降級(jí)第一級(jí)如果是目標(biāo)應(yīng)用未安裝彈一個(gè)提示引導(dǎo)用戶同時(shí)把該渠道在面板里隱藏一段時(shí)間第二級(jí)如果連續(xù)失敗自動(dòng)切到系統(tǒng)分享作為兜底。系統(tǒng)分享雖然拿不到回調(diào)但至少用戶能把內(nèi)容發(fā)出去體驗(yàn)上是部分成功而不是完全失敗。這個(gè)兜底邏輯用 Android 原生的Intent.ACTION_SEND實(shí)現(xiàn)即可不需要額外依賴Intent intent new Intent(Intent.ACTION_SEND); intent.setType(text/plain); intent.putExtra(Intent.EXTRA_TEXT, 正文內(nèi)容 https://你的域名/detail?id123); context.startActivity(Intent.createChooser(intent, 分享到));記得判空resolveActivity否則在沒有可分享應(yīng)用的設(shè)備上會(huì)拋異常。5.3 埋點(diǎn)把分享這件事量化出來分享功能的業(yè)務(wù)價(jià)值需要通過數(shù)據(jù)說話。我一般埋三個(gè)點(diǎn)面板曝光用戶看到了哪些渠道、渠道點(diǎn)擊用戶選了哪個(gè)、結(jié)果回調(diào)成功/失敗/取消帶錯(cuò)誤碼。這三個(gè)點(diǎn)串起來能算出每個(gè)渠道的點(diǎn)擊率、成功率、失敗原因分布。有了這組數(shù)據(jù)很多決策就有依據(jù)了。比如某個(gè)渠道成功率長(zhǎng)期低于 80%先去查是不是版本兼容問題某個(gè)渠道點(diǎn)擊率高但成功率低可能是參數(shù)配置有問題。沒有數(shù)據(jù)的團(tuán)隊(duì)只能靠用戶投訴來發(fā)現(xiàn)問題滯后性好幾天。埋點(diǎn)實(shí)現(xiàn)上有個(gè)細(xì)節(jié)回調(diào)可能在非主線程寫數(shù)據(jù)庫或者上報(bào)要注意線程切換。另外分享面板的曝光時(shí)機(jī)建議放在show()之后延時(shí)一小段避免把面板初始化失敗也算成曝光。5.4 版本升級(jí)的回歸清單SDK 升級(jí)不是換個(gè)版本號(hào)就完事。我整理了一份自己的回歸清單每次升級(jí)按這個(gè)走一遍初始化是否正?？慈罩?、面板是否能彈出、每個(gè)渠道是否都能走通、回調(diào)是否正常觸發(fā)、Release 包混淆后是否正常、低版本 Android尤其是 7.0 和 11是否正常、未安裝目標(biāo)應(yīng)用時(shí)提示是否正確。這七項(xiàng)跑完大概二十分鐘但能避免上線后回滾。我吃過一次虧升級(jí)后功能全對(duì)但忘了驗(yàn)證 Android 11 的包可見性結(jié)果新系統(tǒng)用戶全部無法分享緊急發(fā)版修了兩天才穩(wěn)住。最后分享一個(gè)我自己的習(xí)慣。每次集成或升級(jí)完分享功能我會(huì)在真機(jī)上用三無環(huán)境測(cè)一遍——沒有緩存、沒有登錄、剛裝的包。這個(gè)環(huán)境最接近新用戶很多因?yàn)楸镜貭顟B(tài)殘留而被掩蓋的問題會(huì)立刻暴露出來。踩過幾次坑之后這個(gè)動(dòng)作已經(jīng)變成我的肌肉記憶了。