详细接入流程

一、快速体验

一个完整的WMPF开发流程包括体验demo、设备注册、WMPF Client开发和小程序开发三个过程,如果已经有适合在设备上运行的小程序,则无需重新开发小程序。

1. 注册微信终端合作平台(wecooper平台)账号

你需要在微信终端合作平台(wecooper)平台注册账户,合作的申请、设备的注册授权、小程序的绑定等步骤都必须在wecooper平台完成:

  1. 若你还未确定是否采用WMPF开发商用设备,希望短时间体验小程序运行在你的设备上的效果,判断小程序是否适合你的设备,并评估开发成本,可在申请账户时选择“个人开发者试用”。“个人开发者试用”只能使用快速体验demo。
  2. 若你已确定采用WMPF开发商用设备并计划公开发布,请选择“企业合作申请”;请提前准备企业简介、执照、授权函等材料用于账号注册审核。

账号注册申请提交后,预计1-3个工作日内完成审核,审核通过后将会收到邮件通知。

2. 下载体验包

快速体验包支持在设备上运行一个指定的小程序。你可以将demo和WMPF安装到你的设备中,并运行你需要的小程序,体验小程序在设备上的使用效果。

你需要:

  1. 进入wecooper平台的“快速体验”页面
  1. 在页面中下载demo apk和WMPF apk的安装包,并阅读压缩包中的操作指引;根据指引将demo和WMPF安装到Android设备中,启动并保证两个apk处于运行状态,其中demo apk界面保持在前台
  1. 在手机微信中启动小程序,点击“…”,点击小程序名称,进入小程序信息页,点击“…”-“更多资料”查看小程序appID
  1. 在平台上输入小程序appID,点击搜索按钮,生成ticket;再将生成的ticket输入到设备上运行的demo apk中,从而启动小程序。

在正式开发中,需要绑定小程序之后才能在设备中运行小程序,为了使体验demo获得运行小程序的权限,ticket会作为小程序的临时启动凭证,2小时后需要重新获取ticket。

Demo支持运行正式版、体验版和开发版小程序;后续版本将会支持对体验demo的定制开发(demo apk本质上是一种简易的WMPF Client,你可以在其基础上进行二次开发,低成本地验证WMPF Client的开发周期)。

二、WMPF Client开发

1. 详细阅读开发指引,下载WMPF Service apk

请详细阅读本文档,理解WMPF的技术原理和各个名词概念,以便流畅地完成本项目的开发。如有疑惑可到github issue提交区反馈,或发送邮件到wecooper@tencent.com。

WMPF apk请到github release区下载:

形如wmpf-arm-alpha-release-v7.0.10.51-411.apk的文件(带有alpha字样)是开发版本,带有WMPF的测试界面;仅供开发和测试过程使用;

形如wmpf-arm-production-release-v7.0.10.51-411.apk的文件(带有production字样)是正式版本,没有操作界面;仅供正式上线后使用;

形如wmpf-cli-release-v1.0.2-rc1.aar的文件是aar文件,需要下载后集成在WMPF Client中; Source code文件为github自动生成,可忽略。

2. 创建移动应用

微信开放平台创建移动应用之后,你会获得移动应用ID,又称HostAppID。它用来表示设备的合作方,所有需要运行的小程序都需要将小程序AppID与你的移动应用ID相绑定。

  1. 打开微信开放平台网站,注册开放平台账号(如果已有开放平台账号,可直接登录)。注册账号需要填写企业名称、简介、注册主体、官网链接、注册人身份证明等信息。

请注意: 请确保用户可以在官网了解你的业务和功能,若官网信息和你申请的实际功能不相符,创建移动应用审核可能会被拒绝。每次发起创建移动应用的审核时间约3-7个工作日,请谨慎对待。

  1. 点击“移动应用开发”下的“了解更多”,点击“创建应用”,按照提示提交相关信息。提交审核后约3-7个工作内,审核结果会通过邮件通知;若审核通过,可获得你的移动应用ID及对应的app secret。

请注意: 创建移动应用时需要注明该应用用于“WMPF微信小程序硬件框架”,产品的流程图、原型图也应一并提交。如有疑问,请随时与我们联系(可到github issue提交区反馈,或发送邮件到wecooper@tencent.com)。

请注意: 若你希望在设备使用时调用登录用户的微信头像和名字,则需要申请开发者资质的认证。

3. 注册硬件设备

WMPF要求接入设备硬件信息必须预先在wecooper平台完成注册,方可使用,每一台设备的设备ID(Device ID)都必须通过相应接口传递到微信后台。

  1. 添加设备类型

微信需要了解你的设备应用的行业和预计的出货规模,所以微信会核实你所提供的信息并反馈审核结果,请如实填写。

登录你的wecooper平台账户,点击左侧“管理接入设备”,添加希望上线小程序硬件框架的设备类型,选择所属的行业类型,填写出货量(预测)信息,并点击提交。等待微信侧审核(约1-3个工作日)。审核通过后可在“管理接入设备”页面中获得Product ID。

请注意: WMPF不支持在手机、PC等通用型设备上运行,请选择其他硬件设备提交申请。

请注意: Product ID对应一种设备类型,如果你申请了多个设备类型接入WMPF,你就会获得多个Product ID。Product ID会被用于后续的设备信息上传过程中。

  1. 添加设备机型

接着,你需要提交设备的机型名称等信息,这些信息可以帮助你在wecooper平台上区分提交的多种设备。你还需要提交model name,可以将它理解成机型的“英文名”,它会被用到开发代码中。

例如:开发者希望在即将发布的,代号为“视野”的C-280型号电视机上线WMPF能力,填写示例如下:

1)设备类型:选择“电视”

2)行业类型:选择“智能家居”

3)机型:视野

4)model name:C-280

在这一步中,你还需要提交设备公钥,将对应私钥保存在本地,微信会通过一对公私钥来判断设备授权是否合法。你可能会注意到,在后续的开发过程中,你还需要获取KeyVersion、Signature和你自己定义的deviceId,以便在开发Client Apk时使用。关于公私钥的生成方法和Key Version、Signature和Device Id,请参考硬件注册步骤的指示完成操作。

请注意: 文档中提到的后台API接口,需要在完成“3)绑定移动应用ID和小程序”步骤后才能使用。

通过设备类型审核后,请点击左侧“管理接入设备”,选择需要添加设备机型的设备类型,点击“添加”。在新页面中,勾选“微信小程序硬件框架”,并输入“机型名”和“model name”。点击下方“公钥”下的“点击添加”,并将公钥信息复制到页面文本框中。请注意核对公钥的格式,格式错误将导致审核失败。点击“添加”确认提交,等待微信侧审核(约1-3个工作日)。

  1. 绑定移动应用ID和小程序

WMPF要求必须至少绑定1个小程序后,才能获得上传设备信息的接口。每一个移动应用ID最多可绑定的小程序数量限制:

  • 非同主体小程序(小程序和移动应用的主体不是同一个):最多50个;
  • 同主体小程序(小程序和移动应用的主体是同一个):数量不限。

如果有更多绑定需求,可再次创建移动应用。但需要注意的是,同一台设备上只能绑定一个移动应用ID。小程序开发者可在微信公众平台后台关闭对设备的授权,授权关闭后,小程序将不能再在该机型上使用。

在绑定移动应用ID的时候,必须同时输入access_token(点击查看如何获取access_token)。这是一个动态更新的代码,每隔72小时更新一次。

绑定移动应用ID:

登录微信开放平台,点击“管理中心-应用详情”查看移动应用ID(显示为AppID)。登录wecooper平台,点击左侧“绑定小程序”,点击“添加”,在“APP ID”中输入你在微信开放平台创建的移动应用ID和access_token,并选择要绑定的设备类型。

如果你已经发布过自己的小程序,可以直接绑定你的小程序;如果你没有小程序,可以选择绑定其他第三方开发的小程序。

绑定现网小程序:

按照下图所示的方式获取小程序AppID,并填写到页面中,即可绑定小程序。

  1. 硬件注册

获得deviceID接口权限:

点击左侧“申请注册设备”,核对右侧是否已经显示在上一步中输入的移动应用ID;若未显示,则点击“添加”,然后勾选“微信小程序硬件框架”,并在“APP ID”下方填入移动应用ID。

至此,你已完成“deviceID”接口的权限获取,请按照 注册deviceID接口文档的指示,通过后台API接口对所有希望接入WMPF的设备进行激活。关于公私钥的生成方法和KeyVersion、Signature和DeviceId,请参考硬件注册步骤的指示完成操作。

通过接口注册硬件:

请按照硬件注册步骤的指引,通过后台API接口操作。

productId代表某一种产品,如微信相框,每个微信相框都有专属的deviceId和signature,也就是说出厂的每台微信相框productId可以相同,但这些微信相框的deviceId和signature需对应唯一机器。若出现一码多机共用的情况,WMPF将无法启动。deviceId和signature不一定要hard code在代码中,可以根据机器sn码动态生成,也可以动态下发,保证唯一性即可。productId, keyVersion, deviceId, signature这些参数将用于激活设备。

完成以上步骤后,你的设备就完成了注册过程。

4. WMPF Client开发

当我们在一台已经完成了WMPF全部开发流程的设备上启动小程序时,WMPF会依据之前提供的硬件注册信息进行设备实时激活,激活成功后才可正常使用。时序图见下方:

为了方便的你的理解和开发,我们强烈建议你通过fork或clone WMPF-demo(微信提供的简易版WMPF Client)代码的方式来进行开发。

  1. 复制代码

*clone或fork wmpf-client-demo仓库的代码到你的github项目中,在Android Studio中导入运行wmpf-client-demo。

  1. 填入硬件注册信息

*将前面硬件注册步骤获取到的KeyVersion,Signature和你自己定义的deviceId以及wecooper获取的Product ID等信息填入DeviceInfo.kt

  1. 填入移动应用信息

*将前面申请移动应用获取到的hostAppId和 APPSECRET,填入https://github.com/wmpf/wmpf_demo_external/blob/master/wmpf-demo/app/build.gradle。

*设置DeviceInfo.isInProductionEnv = true。

  1. IPC交互协议 阅读Service与Client的IPC交互协议,了解如何与WMPF Service进行通信,并成功激活设备和launch你的小程序。

*编译运行WMPF-demo,然后按下列动图中的步骤操作,你就可以打开小程序了。

祝贺你,现在准备工作已经完成,你可以进一步修改定制你的Client了。

  1. 优化
  • WMPF Push能力:小程序未在前台运行时,也可以通过服务器向WMPF push消息,开发者可自行定义push消息的样式;也可从消息中跳转到小程序或小程序内的指定页面。本能力适用于场景较丰富,同时使用的小程序较多的场景。详情请访问:WMPF Push能力文档
  • WMPF专有接口(JSAPI):关于未在小程序中定义的特殊安卓接口,部分常用硬件(如打印机、定焦摄像头)可以通过WMPF专有接口来直接调用。详情请访问:WMPF专有接口
  • WMPF调用通道(Invoke Channel):若设备需要调用特殊的本地能力,而手机微信小程序并未定义相关接口,可通过该通道透传相关信息。详情请访问: WMPF调用通道文档
  • 分包加载和预加载:对于硬件性能较差,或网络状况较差的情况,可以通过分包加载来提升小程序启动时的流畅程度;也可启用预加载功能,小程序首次启动后部分数据将存储在本地,下次启动速度会明显优化。详情请访问:Service与Client的IPC交互协议文档,查看InvokerTask_PreloadRuntime参数。
  • 横屏优化:如果你的设备屏幕方向为横向,但是需要使用手机上为竖屏设计的小程序,可以打开横屏强制居中显示。详情请访问:Service与Client的IPC交互协议文档,查看IPCInvokerTask_LaunchWxaApp参数。