”搖一搖周邊“是微信提供的一種新的基於位置的連接方式。用戶通過“搖一搖”的“周邊”頁卡，可以與線下商戶進行互動，獲得商戶提供的個性化的服務。微信4月份有一個贈送搖一搖設備的活動，我們有幸獲得贈送資格，取得一個搖一搖的設備用來測試這個新增的、很有潛力的功能。”搖一搖周邊“是微信基於低功耗藍牙技術的 O2O 入口級應用，與微信的其他線下連接能力一道，加速促成了微信 O2O 閉環的實現。本文主要介紹一搖設備的配置使用，以及如何在開發層面上，定義及實現微信搖一搖的功能接口。
1、IBeacon基礎知識介紹
搖一搖周邊是基於IBeacon來實現的。IBeacon是蘋果公司開發的一種通過低功耗藍牙技術進行一個十分精確的微定位技術。IBeacon設備通過藍牙信號廣播設備id, 手機等終端進入IBeacon設備的信號范圍，可以收到該設備的id.
實現分如下四個步驟：
第一步. 服務提供者向微信后台申請服務，微信后台生成一個IBeaconId,並將其映射到服務提供者提供的服務，再將IBeaconId告訴服務提供者;
第二步. 服務提供者把第一步拿到的IBeaconId設置到IBeacon設備上，讓IBeacon設備廣播該IBeaconId;
第三步. 用戶在該IBeacon設備的信號范圍內打開微信搖一搖周邊，微信App拿到該IBeaconId;
第四步. 微信通過第三步拿到的IBeaconId，向微信后台拉取相應的服務，展示在搖出來的結果上。
第五步. 用戶點擊搖出來結果，在微信內嵌的瀏覽器上，會帶上用戶信息跳轉到服務提供者在第一步申請服務時填的url，進入應用頁面
應用場景：
2、搖一搖設備的使用
搖一搖的beacon設備很小，底座可以用贈送的雙面膠粘貼在牆面上，底面還可以貼一個微信的提示標簽，挺有意思的效果。
同時可以下載這個beacon設備的App軟件RealKit進行設置設備，設備界面管理界面如下所示。
根據官方搖一搖（https://zb.weixin.qq.com/）的配置說明，我們擁有設備后，需要配置設備響應的頁面，流程如下所示。
由於是微信贈送的設備，默認情況下，微信后台已經給我們添加贈送的搖一搖設備記錄了；
如果是自己購買這種搖一搖的設備，那么需要自己手工添加設備記錄，並輸入相關的參數即可。
添加設備后，我們需要配置搖一搖的頁面，頁面就是在搖動微信的時候，顯示給微信用戶的一個界面，頁面管理界面如下所示。
最終配置完成后，我們就來試一下這個神秘的設備了，看看效果如何。這個設備的信號穿透力還是很不錯，隔了10米，兩堵牆搖一搖還是很快出來界面的。
這個搖一搖周邊的功能，我在IPhone4S里面始終無法出現周邊這個模塊，在5、6plus里面倒是很正常的出現並響應處理，而IPAD則是在搖一搖后出現頁面的，但是頁面無法響應。
3、基於C#的微信搖一搖接口的實現
搖一搖和功能界面相呼應，提供了設備管理、頁面管理、素材管理、關聯關系綁定、設備及用戶信息、數據統計等功能接口，如下所示。
1）設備管理
而其中設備管理部分，又分為了好幾個API的處理。
1 申請設備ID
2 編輯設備信息
3 配置設備與門店的關聯關系
4 查詢設備列表
申請設備ID
接口說明 申請配置設備所需的UUID、Major、Minor。申請成功后返回批次ID，可用返回的批次ID用“查詢設備列表”接口拉取本次申請的設備ID。單次新增設備超過500個，需走人工審核流程，大概需要三個工作日；單次新增設備不超過500個的，當日可返回申請的設備ID。一個公眾賬號最多可申請99999個設備ID，如需申請的設備ID數超過最大限額，請郵件至zhoubian@tencent.com，郵件格式如下： 標題：申請提升設備ID額度 內容：1、公眾賬號名稱及appid（wx開頭的字符串，在mp平台可查看） 2、用途 3、預估需要多少設備ID。
接口調用說明
http請求方式: POST（請使用https協議） https://api.weixin.qq.com/shakearound/device/applyid?access_token=ACCESS_TOKEN POST數據格式：json POST數據例子： { "quantity":3, "apply_reason":"測試", "comment":"測試專用", "poi_id":1234 }
參數說明
| 參數 | 是否必須 | 說明 |
|---|---|---|
| access_token | 是 | 調用接口憑證 |
| quantity | 是 | 申請的設備ID的數量，單次新增設備超過500個，需走人工審核流程 |
| apply_reason | 是 | 申請理由，不超過100個字 |
| comment | 否 | 備注，不超過15個漢字或30個英文字母 |
| poi_id | 否 | 設備關聯的門店ID，關聯門店后，在門店1KM的范圍內有優先搖出信息的機會。門店相關信息具體可查看門店相關的接口文檔 |
返回說明 正常時的返回JSON數據包示例：
當申請個數小於等於500時，
{
"data": {
"apply_id": 123,
"device_identifiers":[
{
"device_id":10100,
"uuid":"FDA50693-A4E2-4FB1-AFCF-C6EB07647825",
"major":10001,
"minor":10002
}
]
},
"errcode": 0,
"errmsg": "success."
}
當申請個數大於500時，
{
"data": {
"apply_id": 123,
"audit_status": 0,
"audit_comment": "審核未通過"
},
"errcode": 0,
"errmsg": "success."
}
參數說明
| 參數 | 說明 |
|---|---|
| device_identifiers | 指定的設備ID列表 |
| device_id | 設備編號 |
| UUID、major、minor | UUID、major、minor |
| audit_status | 審核狀態。0：審核未通過、1：審核中、2：審核已通過；審核會在三個工作日內完成 |
| audit_comment | 審核備注，包括審核不通過的原因 |
| apply_id | 申請的批次ID，可用在“查詢設備列表”接口按批次查詢本次申請成功的設備ID。 |
根據這些接口定義，我們可以創建一個搖一搖專用的接口類IShakeAround。
/// <summary> /// 搖一搖周邊的接口定義 /// </summary> public interface IShakeAround { #region 設備管理 /// <summary> /// 申請設備ID。 /// 接口說明 申請配置設備所需的UUID、Major、Minor。 /// 若激活率小於50%，不能新增設備。單次新增設備超過500個，需走人工審核流程。審核通過后，可用返回的批次ID用“查詢設備列表”接口拉取本次申請的設備ID。 /// </summary> /// <param name="accessToken">調用接口憑證</param> /// <param name="applyInfo">設備申請信息</param> ShakeDeviceApplyJson ApplyDevice(string accessToken, ShakeDeviceAddJson applyInfo); /// <summary> /// 編輯設備信息。 /// 接口說明 編輯設備的備注信息。可用設備ID或完整的UUID、Major、Minor指定設備，二者選其一。 /// </summary> /// <param name="accessToken">調用接口憑證</param> /// <param name="info">設備信息</param> /// <param name="comment">設備的備注信息，不超過15個漢字或30個英文字母。</param> /// <returns></returns> CommonResult UpdateDevice(string accessToken, ShakeDeviceIdentifier info, string comment); /// <summary> /// 配置設備與門店的關聯關系。接口說明 修改設備關聯的門店ID、設備的備注信息。可用設備ID或完整的UUID、Major、Minor指定設備，二者選其一。 /// </summary> /// <param name="accessToken">調用接口憑證</param> /// <param name="info">設備信息</param> /// <param name="poi_id">待關聯的門店ID</param> /// <returns></returns> CommonResult BindDevice(string accessToken, ShakeDeviceIdentifier info, int poi_id); /// <summary> /// 查詢設備列表. /// 接口說明 查詢已有的設備ID、UUID、Major、Minor、激活狀態、備注信息、關聯門店、關聯頁面等信息。可指定設備ID或完整的UUID、Major、Minor查詢，也可批量拉取設備信息列表。 /// </summary> /// <param name="accessToken">調用接口憑證</param> /// <param name="device_identifiers">設備列表信息</param> /// <returns></returns> ShakeDeviceSearchList SearchDevice(string accessToken, List<ShakeDeviceIdentifier> device_identifiers); /// <summary> /// 查詢設備列表. /// 接口說明 查詢已有的設備ID、UUID、Major、Minor、激活狀態、備注信息、關聯門店、關聯頁面等信息。可指定設備ID或完整的UUID、Major、Minor查詢，也可批量拉取設備信息列表。 /// </summary> /// <param name="accessToken">調用接口憑證</param> /// <param name="data">分頁查詢條件。apply_id為批次ID，如果指定則以批次進行查詢，否則以指定范圍查詢。</param> /// <returns></returns> ShakeDeviceSearchList SearchDevice(string accessToken, ShakeDeviceSearchPaging data); #endregion
接口定義好，我們增加對應的類實現即可，如下是申請設備的接口具體實現函數，其他遵循同樣的規則就不再贅述。
/// <summary> /// 申請設備ID。 /// 接口說明 申請配置設備所需的UUID、Major、Minor。 /// 若激活率小於50%，不能新增設備。單次新增設備超過500個，需走人工審核流程。審核通過后，可用返回的批次ID用“查詢設備列表”接口拉取本次申請的設備ID。 /// </summary> /// <param name="accessToken">調用接口憑證</param> /// <param name="applyInfo">設備申請信息</param> public ShakeDeviceApplyJson ApplyDevice(string accessToken, ShakeDeviceAddJson applyInfo) { var url = string.Format("https://api.weixin.qq.com/shakearound/device/applyid?access_token={0}", accessToken); string postData = applyInfo.ToJson(); ShakeDeviceApplyJson data = null; ShakeDeviceApplyResult result = JsonHelper<ShakeDeviceApplyResult>.ConvertJson(url, postData); if (result != null) { data = result.data; } return data; }
2）頁面管理
同樣頁面管理也包含了幾個不同的方法，用來創建、編輯、刪除頁面等處理操作
1 新增頁面
2 編輯頁面信息
3 查詢頁面列表
4 刪除頁面
新增頁面
新增搖一搖出來的頁面信息，包括在搖一搖頁面出現的主標題、副標題、圖片和點擊進去的超鏈接。其中，圖片必須為用素材管理接口上傳至微信側服務器后返回的鏈接。
接口調用說明
http請求方式: POST（請使用https協議） https://api.weixin.qq.com/shakearound/page/add?access_token=ACCESS_TOKEN POST數據格式：json POST數據例子： { "title":"主標題", "description":"副標題", "page_url":" https://zb.weixin.qq.com ", "comment":"數據示例", "icon_url":"http://3gimg.qq.com/shake_nearby/dy/icon " }
根據這些接口定義，同樣我們可以為IShakeAround接口類增加對應的接口定義了。
#region 頁面管理 /// <summary> /// 新增頁面。 /// 新增搖一搖出來的頁面信息，包括在搖一搖頁面出現的主標題、副標題、圖片和點擊進去的超鏈接。 /// 其中，圖片必須為用素材管理接口上傳至微信側服務器后返回的鏈接。 /// </summary> /// <param name="accessToken">調用接口憑證</param> /// <param name="info">新增頁面POST數據對象</param> /// <returns></returns> ShakePageResult AddPage(string accessToken, ShakePageJson info); /// <summary> /// 編輯頁面信息。 /// 編輯搖一搖出來的頁面信息，包括在搖一搖頁面出現的主標題、副標題、圖片和點擊進去的超鏈接。 /// </summary> /// <param name="accessToken">調用接口憑證</param> /// <param name="info">編輯頁面POST數據對象</param> /// <returns></returns> ShakePageResult UpdatePage(string accessToken, ShakePageJson info); /// <summary> /// 查詢頁面列表。 /// 查詢已有的頁面，包括在搖一搖頁面出現的主標題、副標題、圖片和點擊進去的超鏈接。 /// 提供詢方式:指定頁面ID查詢。 /// </summary> /// <param name="accessToken">調用接口憑證</param> /// <param name="begin">頁面列表的起始索引值</param> /// <param name="count">待查詢的頁面個數</param> /// <returns></returns> ShakePageSearchJson SearchPage(string accessToken, int begin, int count); /// <summary> /// 查詢頁面列表。 /// 查詢已有的頁面，包括在搖一搖頁面出現的主標題、副標題、圖片和點擊進去的超鏈接。 /// 提供詢方式:批量拉取頁面列表 /// </summary> /// <param name="accessToken">調用接口憑證</param> /// <param name="page_ids">指定頁面的id列表</param> /// <returns></returns> ShakePageSearchJson SearchPage(string accessToken, List<int> page_ids); /// <summary> /// 查詢頁面列表。 /// 查詢已有的頁面，包括在搖一搖頁面出現的主標題、副標題、圖片和點擊進去的超鏈接。 /// 提供兩種查詢方式，可指定頁面ID查詢，也可批量拉取頁面列表。 /// </summary> /// <param name="accessToken">調用接口憑證</param> /// <param name="info"></param> /// <returns></returns> ShakePageSearchJson SearchPage(string accessToken, ShakePageSearchPaging info); /// <summary> /// 刪除頁面。 /// 刪除已有的頁面，包括在搖一搖頁面出現的主標題、副標題、圖片和點擊進去的超鏈接。 /// 只有頁面與設備沒有關聯關系時，才可被刪除。 /// </summary> /// <param name="accessToken">調用接口憑證</param> /// <param name="page_ids">指定頁面的id列表</param> /// <returns></returns> CommonResult DeletePage(string accessToken, List<int> page_ids); #endregion 頁面管理
3）其他管理
當然除了上面設備、頁面的管理，還有一些如
上傳圖片素材、配置設備與頁面的關聯關系、以設備為維度的數據統計接口、以頁面為維度的數據統計接口等方法接口用來實現，根據上面的處理方式定義即可。
4）測試代碼
增加相關的接口定義，以及完成對應的接口實現，我們就需要編寫一些測試類來對我們的接口進行測試的，這些對設備、頁面的測試代碼如下所示。
/// <summary> /// 搖一搖設備的申請、修改、綁定處理操作測試 /// </summary> private void btnDevice_Click(object sender, EventArgs e) { try { int poi_id = 275961135; ShakeDeviceApplyJson result = api.ApplyDevice(this.token, new ShakeDeviceAddJson() { quantity = 1, apply_reason = "測試", comment = "測試備注", poi_id = poi_id }); if (result != null) { Console.WriteLine(result.ToJson()); if (result.device_identifiers != null) { ShakeDeviceIdentifier device = result.device_identifiers[0]; if (device != null) { int device_id = device.device_id; //465123; Console.WriteLine(device_id); string comment = "修改的備注"; ShakeDeviceIdentifier info = new ShakeDeviceIdentifier(device.device_id, device.uuid, device.major, device.minor); CommonResult comResult = api.UpdateDevice(this.token, info, comment); MessageUtil.ShowTips(comResult.Success ? "操作成功" : "修改設備失敗:" + comResult.ErrorMessage); comResult = api.BindDevice(this.token, info, poi_id); MessageUtil.ShowTips(comResult.Success ? "操作成功" : "修改設備失敗:" + comResult.ErrorMessage); } } } } catch(Exception ex) { Console.WriteLine(ex); } }
/// <summary> /// 增加搖一搖素材、增加頁面、修改頁面、刪除頁面的操作示例代碼 /// </summary> private void btnPage_Click(object sender, EventArgs e) { string file = FileDialogHelper.OpenImage(false); if(string.IsNullOrEmpty(file)) { return; } ShakeMaterialJson mediaJson = api.AddMaterail(this.token, file); if (mediaJson != null) { ShakePageJson json = new ShakePageJson() { title = "主標題", description = "副標題", comment = "備注說明", page_url = "https://www.iqidi.com", icon_url = mediaJson.pic_url }; ShakePageResult result = api.AddPage(this.token, json); if (result != null) { Console.WriteLine(result.ToJson()); if (result.data != null) { json.page_id = result.data.page_id; json.comment = "修改備注信息"; result = api.UpdatePage(this.token, json); if (result != null) { Console.WriteLine("修改頁面"); Console.WriteLine(result.ToJson()); } CommonResult comResult = api.DeletePage(this.token, new List<int>() { json.page_id.Value }); MessageUtil.ShowTips(comResult.Success ? "刪除頁面操作成功" : "刪除頁面失敗:" + comResult.ErrorMessage); } } } }
個人認為，搖一搖設備，開啟了一個更廣闊的應用空間，隨着越來越多設備商的支持，微信接口的完善和增加，可以迸發出更多有意思、實用的應用場景。