Skip to content

六、Poco-SDK接入指南

1. Android应用

Poco支持绝大部分的Android原生应用,并且无需嵌入Poco-SDK;但对于混合开发、或者含WebView页面的Android应用来说,Poco的支持并不是那么友好,存在获取不到控件的可能性。

所以请同学们在测试这类Android应用时,尽量使用最新版的pocoui和安装最新的pocoservice.apk,我们会努力兼容更多Android应用。

2. iOS原生应用

同Android应用相似,Poco支持iOS原生应用,且无需嵌入Poco-SDK。

3. Unity3D

PocoSDK 支持Unity3D 4以上版本,支持NGUI和UGUI,SDK目前只有c#版。如果你的Unity3D游戏使用了其他GUI框架,请参考 implementation guide 。接入步骤如下:

1)下载Poco-SDK包

这个直接到我们的GitHub上面clone下来即可:https://github.com/AirtestProject/Poco-SDK 。

2)把Unity3D文件夹放到项目脚本中

把刚才clone下来的压缩包 Poco-SDK-master.zip 解压,然后将其中的Unity3D文件夹放到你Unity项目的Scripts的任意位置中:

图片

注意,这里所说的Scripts指的就是unity游戏项目的源码

3)根据UI类型选择

询问程序使用的是哪种UI方式,SDK中有三个文件夹 uguinguifairygui ,保留其中一种删除另外两种,比如上图选择的就是 ugui 。其余两种请务必删除,不然unity会报错。

4)在unity载入脚本

创建一个空的 GameObject (右键-Create Empty),添加脚本(Add Component):

图片

其他参数默认即可,GameObject 名字随意。

或者,同学们也可以在 root 或者 主camera 这些 GameObject 上添加脚本(Add Component) Unity3D/PocoManager.cs

有同学可能会问,为什么要新建空的 GameObject 或者是选择 root 、 主camera 这些 GameObject来添加脚本呢?

其实这都是为了将脚本挂载到1个 不会在游戏的生命周期中被销毁的节点 上去,并且在游戏开始时,尽快开启poco服务。

4. Cocos2dx-lua

Poco-SDK支持cocos2dx-lua版本 >= 3.1,接入步骤如下:

1)下载Poco-SDK包

poco-sdk repo clone或下载源码。

2)把cocos2dx-lua文件夹放到项目脚本中

cocos2dx-lua/poco 文件夹复制到你的游戏项目脚本文件夹中。你可以重命名该文件夹。

3)复制代码到游戏初始化脚本中

将以下代码复制到您的游戏初始化脚本中,来初始化poco-sdk。

local poco = require('poco.poco_manager')
poco:init_server(15004)  -- default port number is 15004, change to another if you like

注意

您的cocos2dx-lua项目至少应该启用 socketsocket.core 模块。poco要求这个模块在运行时设置一个tcp服务器。

注意

如果cocos2dx-lua项目没有 mime 模块,它仍然可以工作,但是有点慢。

4)判断接入成功

(对于Android平台)最好检查一下adb logcat的输出(建议使用Android Studio里的logcat),选择你的应用看下是否有如下输出,如果有则表示接入成功。

../../_images/integration-guild-cocos2dxlua-sdk-started.png

5. Cocos2dx-js

PocoSDK 支持 3.1 <= Cocos2dx version <= 3.13.1 (理论上)。为了确保每个JavaScript引擎的兼容性, 这个JavaScript sdk是用ES5编写的。

cocos2d-x 3.13.1 已经测试通过。接入步骤如下:

1)下载Poco-SDK包

poco-sdk repo clone或下载源码。

2)把cocos2dx-lua文件夹放到项目脚本中

拷贝 cocos2dx-js/Poco 文件夹到你的cocos2dx-js项目脚本目录,任意路径都可以。

3)构建WebSocketServer模块和js绑定

由于sdk需要WebSocketServer,我们应该使用本机代码构建WebSocketServer模块和js绑定。 WebSocketServer是cocos2dx框架的一部分,但默认不包含,因此我们通过以下步骤手动构建它。 另请参阅WebSocketServer参考。 您最好在复制之前备份您的原始websockets文件夹。WebSocketServer的js绑定需要libwebsockets版本== 1.6。如果您的cocos2d-x引擎没有使用 libwebsockets version == 1.6 ,那么在cocos2d-x本身中可能会有一些不兼容问题。

cp -r cocos2dx-js/3rd/websockets <your-cocos-project>/frameworks/cocos2d-x/external/websockets
cp cocos2dx-js/3rd/src/* <your-cocos-project>/frameworks/runtime-src/Classes
  • 编辑 <your-cocos-project>/frameworks/runtime-src/Classes/AppDelegate.cpp. 在适当的位置添加下面2行代码
// include it at top
#include "jsb_websocketserver.h"

// register callbacks of websocketserver
sc->addRegisterCallback(register_jsb_websocketserver);

../../_images/integration-guild-cocos2dxjs-jsbwebsocketserver.png

../../_images/integration-guild-cocos2dxjs-jsbwebsocketserver-2.png

  • 编辑 <your-cocos-project>/frameworks/runtime-src/proj.android/jni/Android.mk. 在你自己的makefile适当位置添加下方的内容, 如果你正在使用AndroidStudio项目, 请编辑 proj.android-studio/jni/Android.mk 并保证路径正确

../../_images/integration-guild-cocos2dxjs-jsbwebsocketserver-3.png

...

$(call import-add-path, $(LOCAL_PATH)/../../../cocos2d-x/external)

LOCAL_SRC_FILES := hellojavascript/main.cpp \
                   ../../Classes/AppDelegate.cpp \
                   ../../Classes/WebSocketServer.cpp \
                   ../../Classes/jsb_websocketserver.cpp

LOCAL_C_INCLUDES := $(LOCAL_PATH)/../../Classes \
                    $(LOCAL_PATH)/../../../cocos2d-x/external/websockets/include/android

LOCAL_STATIC_LIBRARIES := cocos2d_js_static websockets_static

include $(BUILD_SHARED_LIBRARY)
$(call import-module, websockets/prebuilt/android)
$(call import-module, scripting/js-bindings/proj.android)

...
  • 编辑你的 project.json, 按下列顺序将sdk文件名添加到 jsList 中.
{
    // ...
    jsList: [
        // ...
        "src/lib/Poco/sdk/AbstractDumper.js",
        "src/lib/Poco/sdk/AbstractNode.js",
        "src/lib/Poco/sdk/Attributor.js",
        "src/lib/Poco/sdk/DefaultMatcher.js",
        "src/lib/Poco/sdk/IScreen.js",
        "src/lib/Poco/sdk/Selector.js",
        "src/lib/Poco/Cocos2dxNode.js",
        "src/lib/Poco/Cocos2dxDumper.js",
        "src/lib/Poco/POCO_SDK_VERSION.js",
        "src/lib/Poco/Poco.js"
    ]
}

4)重新编译项目

重新编译你的项目。

5)启动Poco-SDK

require('Poco') 会在游戏的第一个初始化脚本中启动PocoSDK,并且不要在游戏的生命周期中销毁它

var PocoManager = window.PocoManager
var poco = new PocoManager()

// add poco on window object to persist
window.poco = poco

6. Cocos-Creator

1)下载Poco-SDK包

poco-sdk repo clone或下载源码。

2)把cocos-creator文件夹放到项目脚本中

在下载好的源码中,打开Poco-SDK/cocos-creator目录,然后将该目录下的整个Poco文件夹复制到待测游戏项目的assets/scripts目录下。

IMG20191213_173027

3)编辑Cocos Js引擎的配置文件

因为SDK需要WebSocketServer的支持,所以我们需要开启WebSocketServer模块。需要注意的是,WebSocketServer已经被cocos creator 2.2.1默认支持,但是默认是没有开启的,所以我们需要按照如下步骤去开启它:

  • 进入引擎目录,修改ccConfig.h文件,如图所示

IMG20191213_173105

IMG20191213_173111

  • 编辑第62行,把 #define USE_WEBSOCKET_SERVER 0 改为 `#define USE_WEBSOCKET_SERVER 1```

IMG20191213_173117

4)在编辑器中添加引入脚本

IMG20191216_100445

如上图所示在你的游戏项目中,选择asserts/Scripts/某个不会销毁的脚本,并在该脚本的onLoad函数中,添加如下脚本:

    onLoad:function(){
        var poco = require("Poco") //此处添加你自己的Poco.js文件的路径
        window.poco = new poco();
        cc.log(window.poco);

    },

IMG20191213_173121

注意,红框圈起来的,要填写你自己的Poco.js的相对路径。

5)构建-编译-运行

然后你就可以开始编译你的项目了。

注意

当前的版本只支持Android和Windows平台。并且Poco只能在打包后使用,不支持预览模式中使用。

require('Poco') 会在游戏的第一个初始化脚本中启动PocoSDK,并且不要在游戏的生命周期中销毁它。

cc.Class({
    extends: cc.Component,

    .....

    //remember to put code in onLoad function
    onLoad: function () {
       .....

        var poco = require("./Poco") // use your own relative path
        window.poco = new poco(); // not destroy
        cc.log(window.poco);

    },

   .....
});

6)打包后在AirtestIDE查看UI树

我们可以打包为Android安装包,接下来再使用AirtestIDE录制脚本。在IDE面板左侧的Poco Assistant窗口中,下拉选择Cocos-Js,然后就能看到生成的UI树了。

IMG20191213_173126

7. Egret

1)下载Poco-SDK包

poco-sdk repo clone或下载源码。

2)修改modules属性

Poco-SDK/Egret/poco/egretProperties.json中修改modules属性,添加红框内相应字段,其中name属性必须为poco

路径可以是相对路径也可以是绝对路径,具体可以参考白鹭引擎说明文档中有关于 modules字段的说明。

添加和修改modules属性

3)执行命令egret build -e

然后通过快捷键 ctrl+呼出终端 在终端中执行命令egret build -e`:

img

4)新建PocoManager对象

在入口文件main.tsrungame 函数中新建类型为PocoManager的对象,并且传入this.stage

img

5)打开代理服务器

最后再终端中输入python -m poco.utils.net.stdbroker ws://*:5003 tcp://*:15004打开代理服务器;

其中websocket端口默认为5003 如果有更改的需要可以在新建pocomanager 的时候传入端口参数。

img

6)使用AirtestIDE连接

① 连接手机浏览器

AirtestIDE支持Android和iOS手机连接,可以在手机上打开Egret页面(或者微信小程序/游戏),然后通过AirtestIDE进行连接,Windows和MacOS版本IDE都可以使用。连接基本原理为:

Egret05

具体步骤如下:

  • 通过usb连接Android手机,确认adb devices连接ok,在电脑上执行如下命令:
adb reverse tcp:5003 tcp:5003

将手机的5003端口映射到电脑的5003端口

  • 在电脑上启动broker:
 python -m poco.utils.net.stdbroker "ws://*:5003" "tcp://*:15004"

启动broker之后,在手机上访问Egret的页面(需要使用全屏模式保证坐标准确)。访问的时候,broker会打印手机连接上的log,如下:

~ python -m poco.utils.net.stdbroker "ws://*:5003" "tcp://*:15004"
server listens on ("0.0.0.0", 5003) transport websocket
server listens on ("0.0.0.0", 15004) transport socket
StdBroker on.
server on accept. <poco.utils.net.transport.ws.MyWsApp object at 0x1100620d0>
  • 打开AirtestIDE连接手机,选择poco Std-broker模式,即可以看到UI层级结构。同时broker会打印连接日志:
server on accept. <poco.utils.net.transport.ws.MyWsApp object at 0x10d03d2d0>
accept from: ('127.0.0.1', 56872)
received_message from ('127.0.0.1', 56323) {"id":"2a0ce828-132e-4d15-a645-55493d7eaf4b","jsonrpc":"2.0","result":{"children"
  • AirtestIDE界面如下:

image

在AirtestIDE里编写脚本并运行,同时可以查看报告。

image

② 连接桌面浏览器

AirtestIDE也支持Windows窗口连接,MacOS窗口支持暂未放出。所以目前需要使用Windows环境连接桌面浏览器,步骤如下:

  • 运行项目,并在浏览器中打开页面,同时启动broker代理python -m poco.utils.net.stdbroker ws://*:5003 tcp://*:15004,如下:

image

AirtestIDE设置windows窗口连接模式,如下设置为使用无嵌入模式:

image

  • 使用AirtestIDE 选定窗口 功能连接浏览器窗口,连接成功后可以IDE中看到浏览器窗口:

image

  • 在AirtestIDE中选定游戏区域,打开设置中poco window area select进行框选:

image

  • 确定区域之后,在AirtestIDE中即可以使用inspector功能进行UI检视:

image

8. UE4

1)下载Poco-SDK包

UE4 Poco SDKPocoSDK 这个文件夹克隆下来,放置到您项目的 Plugins 目录下。如果您项目没有名为 Plugins 的目录的话,需要先创建该目录。

2)重新编译项目

重新编译项目。确认在编辑器的 Edit > Plugins 当中能看到 Poco SDK ,且 Enabled 为被勾选的状态。

如果此时 Enabled 未被勾选,请勾选 Enabled 并按提示重启编辑器/VS。

image

3)运行游戏

运行游戏。

4)使用方法

① 确保pocoui至少是1.0.79版本或以上

更新最新版的Poco,指令为

pip install -U pocoui

注意包名为pocoui,而不是poco。更新完毕后请确认poco的版本号至少为1.0.79。

② 在AirtestIDE查看UI树

当前版本的IDE尚未外放UI树查看时UE4的选项,因为端口与Unity一致,目前可以使用Unity的选项来查看UI树。

而在脚本层面的具体使用方法如下:

from poco.drivers.ue4 import UE4Poco
poco = UE4Poco()
# example
poco("StartButton").click()
③ 使用编辑器模式

如果想用编辑器模式,可以在初始化Poco的时候传入参数,

poco = UE4Poco(ue4_editor=True)

在编辑器预览游戏的几种模式中,选择New Editor Window(PIE),以此来打开一个独立的窗口预览,此方式连接的窗口为编辑器PIE独立窗口模式。

image

目前poco的代码会默认去连带有 Game Preview Standalone 字样的窗口,如下列代码就是连接UE4窗口中带有Game Preview Standalone字样的窗口。

dev = connect_device("Windows:///?class_name=UnrealWindow&title_re=.*Game Preview Standalone.*")

image (1)

使用脚本连接的游戏窗口,并不会嵌入到IDE里面,还是会独立显示在外面。

如果窗口的名字被修改过,有可能导致连接失败,这时大家可以自行修改poco/drivers/ue4/device.py下连接设备的句柄。

当然,大家在IDE中连接窗口时,选择使用 Select Window ,也可以将预览游戏的窗口嵌入到IDE中:

图片

④ 打成Android包测试

我们更推荐大家将项目打包成Android版的包体,接下来就可以直接使用IDE正常录制脚本啦。

5)常见问题

① Poco-SDK未正常启动

Poco SDK 未能正常启动。

确认 Poco SDKEnabled 的状态。确认 .uproject 文件中包含有Poco SDK, 且为Enabled状态。

② 启动游戏报错

启动游戏时报错,Output Log 中信息为

LogPluginManager: Error: Unable to load plugin 'PocoSDK'. Aborting.

请确认PocoSDK.uplugin文件中的"Installed"这一项对应的值是true,且没有"Enterprise"这一项。

9. 其它引擎(自行接入的办法)

如果我们未能提供您游戏项目对应的Poco-SDK,您也可以选择自行接入,按照我们提供的 自行接入的教程文档 ,实现您游戏项目的Poco-SDK。

10. 微信小程序/H5页面

目前我们不保证Poco完全支持微信小程序或者APP内嵌H5页面的情况,如同学们想要尝试的话,可以注意以下事项:

  • 请确保pocouipocoservice.apk使用的是最新版本
  • Android设备上的小程序和H5,请在IDE的poco辅助窗选择Android模式查看
  • iOS设备上的小程序和H5,请在IDE的poco辅助窗选择iOS模式查看
  • 测试微信小程序时,可以百度/谷歌如何设置使用本地内核,在设置使用本地内核之后再来尝试用Poco去获取控件信息

11. Windows

目前仅支持接入了Poco-SDK的游戏窗口,后续可能放出对Windows桌面应用的Poco支持。

12. MacOS

目前暂不支持,后续可能会放出对MacOS桌面应用的Poco支持。