輕應用開發指南

簡介

什麼是輕應用？

輕應用程式是微博為第三方服務（H5頁面）接入微博提供的一套基礎架構和存取服務（Focus On Mobile）。

輕應用程式入口在微博 Page 頁（也叫 Profile 頁、個人首頁），或微博的卡片（Card）中，由接取方以網頁應用的形式開發。

根據展示平台，輕應用分為兩種：桌面瀏覽器上透過iframe 嵌入（以下簡稱Web 版），微博客戶端內透過Webview 展示（以下簡稱H5 版）。你的應用程式可以選擇兩種展示平台之一，也可以二者都支援。

特點

輕應用程式提供符合微博平台屬性的更多接近用戶的管道，促進用戶與商家雙向關係的形成，讓用戶更有效發現並使用服務。

• 接取便利。接入方H5 網頁只需針對微博做少量的兼容工作，就能享受官方客戶端提供的一系統輕應用服務，從而為用戶提供更好的體驗
• 無需授權。如果使用者在登入狀態存取應用，新的框架將預設完成授權，並將 access_token 資訊傳遞給存取方。
• 更多的曝光機會。應用程式上線後會出現在 Page 頁，以及微博 Feed 串流的 card 中。支援 linkcard 接入，在微博中得到更好的展示。
• 開發過程，統一了存取方式和參數。無論是 Web 版或 H5 版，用戶端收到的參數都是相同的，存取方式基本上都一樣。應用程式可以透過瀏覽器 userAgent 區分是 Web 版還是 H5 版。
• 支援存取微博支付，一鍵完成商品支付。
• [Web 版]新增應用程式分享與讚。直接將應用程式分享到微博，並產生卡片展示，快速傳播。
• [Web 版]支援未登入存取應用程式。未登入微博也可以瀏覽應用，必要的時候透過我們的 JS 用戶端喚起登入浮層。
• [Web 版]套用寬度調整為 940 px。不支援原來的 760px，原來的 950 px 改為 940px。

輕應用場景

有的輕應用，更突出的是內頁，如電影、圖書，可能您希望在微博流中直接看到一張卡片，點擊卡片就能直接進入到商品詳情頁直接購買；

有的應用更突出應用首頁，比如網頁遊戲、單頁應用，它們入口唯一，點開應用首頁進去就能玩；

或二者兼而有之，都是可以的。

應用範例

線上4S店（Web & H5版皆可存取）：

H5 版本：

友寶、愛影客

更多輕應用的介紹，請點這裡。

輕應用開發流程

輕應用程式的開發大致分為四個步驟：

• 成為微博開發者
• 應用程式建立
• 應用程式開發
• 應用審核及上線

如下圖所示：

成為微博開發者

開發輕應用程式的第一步，是成為微博公司開發者。

如果您還不是微博開發者，請先登入微博開放平台，然後進入管理中心完善開發者基本資訊和身分認證。

基本資訊部分，直接選擇開發者類型為公司，完成表單。填寫完成後，透過郵箱驗證就可以開始建立應用程式了。

通過身分認證，有利於應用的審核和各種權限的申請，請一併認真填寫。

個人開發者升級為公司開發者

如果已經是個人開發者，需要進入編輯開發者資訊頁面，重新選擇開發者類型為公司，然後儲存資料即可。

應用程式建立

在 Page 輕應用介紹頁，點選建立應用程式按鈕，進入建立表單填入頁面。

完成表單填寫，會自動跳到應用程式的控制台，在應用程式控制台可以進一步完善應用程式的基本資訊。

編輯應用程式資訊

開啟應用程式資訊->基本信息，可以查看應用程式的基本資料。點選編輯，可以進行修改。

測試位址（Web版、H5版）

開啟應用程式資訊->測試訊息，可以看到應用程式的測試位址。因為應用程式還沒通過審核並上線到應用程式廣場，這個地址僅限開發者本人瀏覽訪問。

如果需要其他微博用戶瀏覽，可以將該微博用戶加入測試帳號裡。每個應用測試帳號最多增加 15 人。

應用程式通過文案審核並上廣場後，測試帳號自動失效。

升級為輕應用程式

升級主要指的是原來已經成功創建了的企業應用程式、站內應用程式或個人版Page 應用，升級為輕應用。

由於已經創建了應用的appkey，升級主要包含兩個方面：一是微博開放平台後台將appkey 升級為輕應用類型；二是應用將原來接收的舊參數改為新的參數。

應用程式開發

註：本小節內容包含應用程式開發的全部細節，請根據應用程式的實際情況選擇。

• 只有內頁展示需求的應用，請直接看如何接入微博支付部分；
• 只有主頁展示需求的應用，請從接收框架參數部分開始閱讀；
• 兼而有之的，請完全閱讀。

應用程式建立完成後，就需要進入應用程式的開發過程了。應用開發其實並不複雜，就是如何處理微博框架傳遞過去的參數，並做對應的處理，其間會牽涉到幾個問題：

應用主頁開發：

接收框架參數
Web 版與H5 版的區分
Web 版JavaScript 套件的使用
H5 版如何呼叫微博客戶端的JS API

應用程式內頁開發：

如何接取微博支付
如何接取linkcard

應用程式升級為輕應用程式

#企業應用程式遷移指南

微博客戶端二維碼規則

技術流程

接收框架參數

應用程式框架會透過POST 形式，傳送給存取方頁面一個加密後的參數signed_request，參數中包含了 uid、access_token 等訊息，如果應用程式需要用到，就需要解密後才能使用。

如果是純展示類別應用，可以不用理會這個參數。

有一點要特別注意，就是參數 signed_request 是 POST 方式傳輸的，接入方的頁面如果不支援 POST 接收，可能會無法正確顯示。

signed_request 的加密方式

signed_request 用小數點分隔成兩段，小數點前是校驗資料，小數點後面是真實資料。校驗數據用於確保數據的有效性，例如沒有被篡改過，只有校驗成功的真實數據，才是可信的。

這二者都使用了 base64 編碼，因此需要先進行資料還原。 base64 資料的部分字元在 HTTP 傳輸的過程中可能會被和 URL 中其他字元混淆，因此開發者拿到的 base64 字串，都做了特殊處理。因此 base64 解碼之前，需要先將字串還原為標準的 base64 字元。

还原方式：先根据字符串长度补上相应长度的等号（补上等号后的字符串长度应该是 4 的整数倍），然后将其中所有的 - 替换成 +，所有 _ 替换成 /。

真實資料 base64 解碼後，轉成 JSON 對象，就是開發者需要的資訊了，下文會詳細介紹每個參數。

如何使用校驗資料？

首先，檢查真實資料 base64 解碼後 JSON 中的 algorithm，必須是 HMAC-SHA256。

其次，透過校驗資料進行校驗，校驗方法如下：

校驗資料base64 解碼後（可能是亂碼的字符，不用管它），保存在變數裡，用於後續對比。
對 base64 解碼之前的數據，使用應用的 app secret 進行 sha256 加密，加密後的數據和校驗數據 base64 解碼後的結果必須一致，才能保證數據的有效性。

因此，signed_request 的解密方法已經可以寫出來了。

使用 SDK 進行資料解密

微博開放平台的眾多 SDK 中，PHPSDK 和 JavaSDK 已經內建了 signed_request 解碼功能，可以直接使用。其他語言需要開發者自行完成。

使用PHPSDK 從signed_request 擷取參數

if(!empty($_POST["signed_request"])){
	$o = new SaeTOAuth( WB_AKEY , WB_SKEY  );
	$data = $o->parseSignedRequest($_REQUEST["signed_request"]);
	if($data == '-2'){
		 die('sign is error!');
	} else {
		$_SESSION['oauth2'] = $data;
	}
}

PHPSDK 解密signed_request 的方法如下，供其他語言參考

/**
 * 解析 signed_request
 * @param string $signed_request 应用框架在加载iframe时会通过向Canvas URL post的参数signed_request
 * @return array
 */
function parseSignedRequest($signed_request) {

	// 将 $signed_request 参数，用小数点.分隔成数组，下标0的赋值给 $encoded_sig，下标1的复制给 $payload
	list($encoded_sig, $payload) = explode('.', $signed_request, 2);

	// 对 $encoded_sig 进行 base64 解码，然后赋值给 $sig
	$sig = self::base64decode($encoded_sig);

	// 对 $payload 进行 base64 解码，并将字符串转为 JSON 赋值给 $data
	$data = json_decode(self::base64decode($payload), true);

	// 如果 $data 中的 algorithm 不是 HMAC-SHA256，表示数据校验出错，直接返回 -1
	if (strtoupper($data['algorithm']) !== 'HMAC-SHA256') return '-1';

	// 使用 app secret 对 $payload 进行 sha256 加密
	$expected_sig = hash_hmac('sha256', $payload, $this->client_secret, true);

	// 如果 sha256 加密后的结果和 $sig 是一致的，那么 $data 数据就没问题，直接返回给调用方；否则>表示数据校验出错，返回 -2
	return ($sig !== $expected_sig)? '-2' : $data;
}
/**
* @ignore
*/
function base64decode($str) {
	// 将需要 base64 解码的字符串，按照字符串长度先补上相应的等号（补上等号后的字符串长度应该是4>的整数倍），然后将其中的 - 和 _ 分别替换成 + 和 /，然后对处理后的字符串执行 base64 解码
	return base64_decode(strtr($str.str_repeat('=', (4 - strlen($str) % 4)), '-_', '+/'));
}

signed_request解密後的格式

未登入狀態存取應用程式參數

QQ截图20170209174302.png

#8月1日後所建立的輕應用程式管理位址預設載入appkey的應用程式位址，如第三方有管理位址的需求，請根據origin傳回的欄位進行二次跳轉

登入狀態存取應用，自動授權成功參數

QQ截图20170209174315.png

能正確接收參數以後，應用還需要區分目前所處的平台。

Web版和H5版的區分

應用程式的基本資訊中，可以選擇 Web 版或 H5 版之一，或是二者都相容。如果二者都相容，就必須區分 Web 版和 H5 版。

區分的作用有兩個：一是為了讓不同的裝置下，應用可以適配，以達到最佳的顯示效果；二是，Web 版和H5 版呼叫的Javascript 套件不一樣，區分後，可以減少不必要的JS 程式碼。

應用程式目前可以透過瀏覽器的 userAgent 區分，目前是顯示在 Web 瀏覽器還是微博客戶端中，這也是目前唯一的方式。

Web 版JavaScript 套件的使用

Web 版是透過iframe 來嵌入存取方應用，除了接收框架POST 的參數，還需要和框架進行通訊，例如：iframe高度自適應、取得父頁面的資訊、喚起登入浮層等。

這些都是透過框架提供的一個 JavaScript 檔案來提供的，具體使用方法請閱讀輕應用元件 Web 版元件的呼叫。

H5 版如何呼叫微博客戶端的JS API

微博客戶端自從4.3.0 開始，在Webview 中新增了JS API 功能，方便網頁應用程式透過JS API 呼叫一些系統功能，例如：取得網路狀態、定位資訊、掃描二維碼、查看大圖等功能。

詳細使用方法，請閱讀：輕應用元件 H5 版元件的使用。

如何喚起微博支付

#目前微博支付只支援線下接入，需要接入的開發者，請聯絡wangwei16@staff.weibo.com。

接取微博付款後，可以申請商品類 linkcard 存取。

如何接取linkcard 解析

注意：目前接取商品類linkcard 必須先接取微博支付，請聯絡wangwei16@staff.weibo.com 申請接入微博支付。

什麼是linkcard

一條微博中如果包含一個鏈接，將展示為一個短鏈接，如圖：

#如果連該連結被解析為包含一個物件資料的特殊短鏈，那麼該物件資料就可以在微博訊息流內以卡片形式顯示。這種形態就是微博訊息流 linkcard（連結卡片）解析。

被解析的連結會被替換為miniCard，顯示上更豐富有力，點擊率更高。在微博正文的下面，一般會解析出 linkcard，可以顯示出縮圖、標題、簡介等資訊。解析效果如圖：

linkcard 是接入方網站連結在微博上承載特定功能的必要形式，依賴 linkcard，可以實現視訊連結的直接播放、音訊連結的直接試聽等效果，以及輕應用直接載入。

在用戶分享接入方網站的連結到微博上時，我們將透過連結特徵，識別出該連結是否屬於某個輕應用程式存取方。對於輕應用接入方的鏈接，我們將調用該接入方登記的解析回調接口，獲取事先約定好格式的對象資料。這些能成功取得到物件資料的鏈接，就可以在pc端、行動用戶端展示成 linkcard，並實現使用者點擊後可以完成輕應用程式框架的載入。

優點：存取方只需依照標準、規範的流程開發回呼介面即可快速存取。

缺點：接入方屬於被動接入，回呼介面有失敗率，可能造成個別連結 linkcard 解析不成功。

如何連接 linkcard？

線下提交申請，聯絡 wangwei16@staff.weibo.com。

存取linkcard 存取方需要做的事情

我們先來看看linkcard 的工作流程：

圖中的1、2 具體描述如下：

1、存取方提供解析長URL 符合規則

長URL 符合規則是一個簡單的正規表示式，匹配上的長URL 在轉短鏈時會當做參數用來調用接入方的對象數據回調接口，即圖中的鏈接域名等特徵。

例如，我們要解析某商品為linkcard，則商品的長連結URL 是：http://www.productmall.com/sample/256819，那麼長URL 符合規則應該是：www.productmall. com/sample/。（請注意，http:// 不包含，可變的商品編號也沒有包含在內）

2、接入方提供解析物件資料回呼介面

該介面由接入方來開發。微博平台在通過上面的長 URL 匹配規則，匹配上的長 URL 在轉短鏈時會調用接入方的這個接口，參數為匹配上的長 URL。

存取方判斷參數 URL 為一個正確的需要解析為 linkcard 的頁面時，介面會傳回需要解析的物件數據，理論上不同的參數 URL 會傳回不同的物件資料。反之，介面回傳錯誤，微博平台將認為這個連結不是正常的 linkcard 對象，轉為普通短鏈，不做 linkcard 解析。

物件資料介面

介面請求方式：GET 介面參數：url，符合符合規則的長 URL 介面回傳值：JSON， JSON資料的具體屬性欄位見下表：

QQ截图20170209174337.png

上面的屬性中，類型為object、object array、media link 的，都是包含下一層屬性的，具體說明如下：

image（media link）

QQ截图20170209174349.png

tags（object array）

QQ截图20170209174400.png

例如：

接入方提供的長URL匹配規則：www.productmall.com/sample/

範例連結：http://www.productmall.com /sample/256819

接入方提供的物件資料回呼介面：http://www.productmall.com/api/get_data?url=

則我們的呼叫實例將為： http://www.productmall.com/api/get_data?url=http://www.productmall.com/sample/256819

存取方回傳資料如下：

#（1 ）不接入官方用戶端二維碼喚起功能

{ 
	"display_name": "这是商品的标题", 
	"image": { 
		"url": "http://www.productmall.com/7272.jpg", 
		"width": 120, 
		"height": 120 
	}, 
	"summary": "这是商品的简介", 
	"url": "http://www.productmall.com/sample/256819.html", 
	"tags": [ 
		{ 
			"display_name": "标签1" 
		} 
	], 
	"create_at": "2012-10-18", 
	"object_type": "product" 
}

（2）接入官方客戶端二維碼喚起功能（假如接入方申請後，開放平台給接入方分配的域名 id 為1456439003）

{ 
	"display_name": "这是商品的标题", 
	"id": "1456439003:www_productmall_com_sample_256819", 
	"image": { 
		"url": "http://www.productmall.com/7272.jpg", 
		"width": 120, 
		"height": 120 
	}, 
	"summary": "这是商品的简介", 
	"url": "http://www.productmall.com/sample/256819.html", 
	"tags": [ 
		{ 
			"display_name": "标签1" 
		} 
	], 
	"create_at": "2012-10-18", 
	"object_type": "product"
}

企業應用遷移指南（升級為輕應用）

企業應用程式和輕應用程式最直覺的變化，是視覺效果上沒有了誇張的頭部（大頭像、頭圖、Tab等），更專注內容的展示。

企業應用程式升級為輕應用，需要做兩件事：

1、應用程式 appkey 升級。將 appkey 加入遷移列表，可以聯絡客服信箱：weibo_app@vip.sina.com

2、修改套用的參數。

參數現在改為 POST 傳輸，並且是加密的，如何解密，請參考接收框架參數部分。

企業應用程式升級為輕應用程式以後，參數名稱也會改變。新舊參數的對應關係如下：

#微博客戶端二維碼規則

#使用此規則產生的二維碼圖片，使用微博客戶端掃描後，可以直接進入物件正文頁，而不是內建預設瀏覽器。區別請看下圖：

測試應用程式規則（上廣場前使用）：

應用程式首頁產生的二維碼：http://apps.weibo.com/qrcode/test?uid=xxx&appkey=xxx (這裡的appkey演算法是base62後的appkey）
應用程式內頁沒有測試位址，入庫後就是正式地址

正式地址規則（上廣場後使用）：

應用首頁產生的二維碼：http://apps.weibo.com/qrcode/app?uid=xxx&appkey=xxx (這裡的appkey演算法是base62後的appkey）
應用程式內頁產生的二維碼：http ://apps.weibo.com/qrcode/linkcard?oid=xxx (這裡的oid 是物件入linkcard 庫後產生的id)

輕應用H5版Demo

請使用微博客戶端掃描下方二維碼查看演示Demo：

Demo中涉及的介面詳情詳見以下文件：

輕應用元件文件：http://open.weibo.com/wiki/輕應用H5新版JS

微博支付應用程式存取指南：http://open.weibo.com/wiki/微網誌支付應用程式存取指南

微博API介面文件： http://open.weibo.com/wiki/微博API

應用程式審核與上線

##應用程式完成開發後，就需要提交應用程式審核了。進入微博開放平台，登入後開啟應用，就可以看到提交審核的入口。

輕應用程式需提交廣場審核，審核後到藍v的管理中心－> 設備管理－> 應用程式管理－> 取得更多應用程式- > 應用廣場進行應用安裝，安裝後會產生apps.weibo.com/uid/xxx開頭的地址，請使用此地址在微博內進行推廣，只有此地址會在微博中自動解析成卡片形式。

輕應用審核規範

服務與支援

輕應用存取過程中遇到問題，請聯絡wangwei16@staff.weibo.com

← 輕應用程式存取指南

輕應用H5新版JS →