Xbox Unity 接入

一、Unity PlayerSettings配置

Build Type

• 开发可设置为Development player，发布需要设置为Master player

Deploy Method

• 开发可设置为Push,发布需要设置为Package

Scripting Define Symbols

• 添加USE_MS_GAMECORE;MICROSOFT_GAME_CORE;

Allow 'unsafe' Code

• 需要勾选

Active Input Handling

• 设置为Input System Package(New)

Package Identity Name

• 合作伙伴中心后台获取

Package Identity Publisher

• 合作伙伴中心后台获取

Title ID

• 需要微软签约操作后在合作伙伴中心后台获取

SCID

• 需要微软签约操作后在合作伙伴中心后台获取

MSA App ID

• 合作伙伴中心后台获取

Store ID

• 合作伙伴中心后台获取

Persistent Local Storage

• 根据游戏存储使用情况设置，range (256Mb-4096Mb)

ContentID Override

• 可选配置，方便本地测试支付功能，需要后台发布后、从商店下载包，然后使用xbapp list /d 查看包的contentId,和EKBID同时替换后本地出包即可测试支付，无需传包到后台发布从商店下载才能测试

EKBID Override

• 可选配置，方便本地测试支付功能，需要后台发布后、从商店下载包，然后使用xbapp list /d 查看包的EKBID，和ContentID同时替换后本地出包即可测试支付，无需传包到后台发布从商店下载才能测试

Default Display Name

• Package Identity Name值“.”分割的后半段

Publisher Display Name

• Package Identity Name值“.”分割的前半段

二、好友组队流程

三、接口

平台提供sdk时确保Assets/Plugins/XboxOne/Logic/Configuration.cs里的单点登录配置SANDBOX_SIGNAL_SIGNON_URL替换成游戏的单点登录配置

1、设置平台参数接口

调用类	DHSDKHelper
接口	setHostPlatformParam
参数	json字符串 json value都为string，key定义如下： DHAppId（产品id） DHChannelId（渠道id） DHInviteCode（邀请码） HostUrl（域名） HostPlatformAppId（titleId） HostPlatformAppkey（scid） mainChannel (主渠道号) subChannel （次渠道号）
调用说明	在初始化接口调用之前设置平台参数

2、获取商品信息接口

调用类	DHSDKHelper
接口	querySkus
参数1	商品id列表
参数2	回调,回调的requestCode为DHSDKHelper.DHSDKConst.REQ_SKUS
说明	查询结果成功但是返回空列表，需要去商店获取游戏才能查询到商品

返回值说明

字段	说明	备注
item_id	商品id,xbox需要先配置商品生成id后给游戏使用，而不是游戏先定义好id配到后台
name	商品名称
currency	货币
formatted_value	格式化字符串	游戏内展示
raw_value	价格

返回值resultData样例

{
    "target":[{"item_id":"9NGHKPF3J53B","name":"test product","currency":"USD","formatted_value":"$0.00","raw_value":"0","owned":true}]
}

3、好友信息同步回调

回调信息	回调的requestCode为DHSDKHelper.DHSDKConst.REQ_FRIENDS_INFO_CHANGE
回调说明	当好友信息变化时收到该回调(比如添加好友、拉黑好友、好友xbox在线、好友xbox离线、好友进入游戏、好友离开游戏等等)，每次返回的都是全量好友信息，如果userId为"0"，说明没有玩过当前游戏

回调对象字段	类型	说明
nickName	string	玩家Xbox昵称
iconUrl	string	玩家头像链接
userId	string	用户id
xboxUid	string	xbox账号id(仅供参考，不一定唯一)
inGame	bool	是否在当前游戏
xboxOnline	bool	是否xbox在线
precenseText	string	丰富状态文本

返回的resultData字符串格式如下：(可以使用JsonUtility.FromJson< DHXboxGameFriendListBean>(data)反序列化对象)

{
    "target": [{
        "nickName": "2 Dev 158707133",
        "iconUrl": "https://images-eds-ssl.xboxlive.com/image?url=8Oaj9Ryq1G1_p3lLnXlsaZgGzAie6Mnu24_PawYuDYIoH77pJ.X5Z.MqQPibUVTcS9jr0n8i7LY1tL3U7AiafX4CBXlmeNYIlNDtmq5GybCrf_ehzIV6VDRULqrr283j&format=png",
        "userId": "189850304",
        "xboxUid": "2814637561506387",
        "inGame": true,
        "xboxOnline": true,
        "precenseText": "Metaverse Keeper"
    }, {
        "nickName": "2 Dev 763610406",
        "iconUrl": "https://images-eds-ssl.xboxlive.com/image?url=z951ykn43p4FqWbbFvR2Ec.8vbDhj8G2Xe7JngaTToBrrCmIEEXHC9UNrdJ6P7KIwuPiuIs6TLDV4WsQAGzSwhtPXK324jSFISZXwjn7Pxep.qUTgu_FaqU1f_RnUzRI&format=png",
        "userId": "189748005",
        "xboxUid": "2814659124966292",
        "inGame": true,
        "xboxOnline": true,
        "precenseText": "Metaverse Keeper"
    }]
}

4、创建房间接口

调用类	DHSDKHelper
接口	createLobby
调用说明	前提是需要在Xbox后台->Xbox服务->游戏设置->多人游戏->多人会话->创建名为LobbySession的会话
回调说明	回调的requestCode为DHSDKHelper.DHSDKConst.REQ_CREATE_LOBBY
其他说明	如果使用好友组队功能，需要在Assets/StreamingAssets目录下放置文件名为session_image.jpg的邀请图片，尺寸为457x257

LobbySession的模板如下，maxMembersCount需要修改成项目实际的房间总人数

{
   "constants": {
        "system": {
            "version": 1,
            "maxMembersCount": 2,
            "visibility": "open",
            "inviteProtocol": "game",
            "capabilities": {
                "connectivity": true,
                "connectionRequiredForActiveMembers": true,
                "gameplay" : true,
                "crossPlay": true,
            },
        },
          "custom": { }
    }
}

回调对象字段	类型	说明
sessionId	string	房间会话ID

创建成功后的返回信息如下：(可以使用JsonUtility.FromJson< DHXboxTeamSessionInfo>(data)反序列化对象)

{"sessionId":"aaa9a701-b2f5-4983-b448-6f3560880ea1"}

5、邀请好友接口

调用类	DHSDKHelper
接口	inviteFriend
调用说明	调用前提是玩家已在房间中，调用接口后会自动拉起系统界面，选择指定玩家后发送邀请。

6、接受好友邀请回调

回调信息	回调的requestCode为DHSDKHelper.DHSDKConst.REQ_RECEIVE_FRIEND_INVITE
回调说明	收到该回调说明用户已经接受好友邀请并且已经成功登录游戏，Xbox要求收到回调后停止一切行为强制进入好友房间，游戏清理完场景后需要调用joinFriendLobbyByInvited接口进入好友房间，收到进入房间成功回调才算真正进入好友房间。游戏需要控制好UI界面来衔接整个强制进入房间过程

7、加入好友邀请的房间

调用类	DHSDKHelper
接口	joinFriendLobbyByInvited

8、主动加入好友的房间

调用类	DHSDKHelper
接口	joinFrinedLobby
参数	账号id
调用说明	该接口适合游戏内展示好友列表的UI里调用，如果好友已经在房间里并且没有满员，可以主动调用该接口加入房间

#

9、离开房间

调用类	DHSDKHelper
接口	leaveLobby

#

10、房间的相关回调

回调信息码	回调说明
DHSDKHelper.DHSDKConst.REQ_LOBBY_JOINED	本人加入房间回调(非房主会收到)，resultData返回全量人员信息
DHSDKHelper.DHSDKConst.REQ_LOBBY_LEAVE	本人离开房间回调
DHSDKHelper.DHSDKConst.REQ_MEMBER_JOINED_LOBBY	成员加入房间回调，resultData返回全量人员信息
DHSDKHelper.DHSDKConst.REQ_MEMBER_LEAVE_LOBBY	成员离开房间回调，resultData返回全量人员信息
DHSDKHelper.DHSDKConst.REQ_LOBBY_HOST_CHANGE	房主变化回调，resultData返回全量人员信息

DHXboxTeamInfo房间类说明

变量名称	类型	说明
sessionId	string	房间会话ID
userInfo	List< DHXboxTeamUserInfo>	成员信息列表

DHXboxTeamUserInfo成员信息类说明

变量名称	类型	说明
accountid	string	房间会话ID
isHost	bool	成员信息列表

resultData返回示例：

{
    "sessionId": "27792822-7a65-43ee-a068-de45769b068f",
    "userInfo": [{
        "accountid": "189918468",
        "isHost": true
    }, {
        "accountid": "189748005",
        "isHost": false
    }]
}

11、其他接口参照基本接口调用接入即可

四、 Q&A

1、登录报错 8015DC12，修改主机Sandbox Id为发布的沙箱ID（比如ZZNHSP.0） 登录报错87DD0019，失去连接需要退出游戏重进 登录报错87DD0021 ,确认unity 工程内单点登录的url是否是Xbox后台配置的依赖url 2、导入GDK-MS-PC报错，unsafe，请修改平台支持unsafe mode; 3、Input System，在Package Manager安装插件 4、平台宏定义USE_MS_GAMECORE;MICROSOFT_GAME_CORE 5、store商店无法搜索任何app，需要解锁国行，切换区域为美国https://www.doyo.cn/article/443600 6、切换开发模式，如果dev mode activition总提示更新后才能激活，请使用隐藏模式， To access the hidden menu go to Settings > System > Console Info > Press LB RB LT RT > Developer Settings > Developer Mode 7、测试支付功能，首次现在商店上传包体发布后，需要在商店下载后从商店启动。 然后使用xbapp list /d 查看包的contentId和ekbId。然后需要在测试Loose目录下MicrosoftGame.config 中添加以下部分：

  <StoreId>9NTL0QDWZ4FS</StoreId>
  <DevelopmentOnly>
    <ContentIdOverride>2797FA46-A93B-494C-AD80-B67C9FCA939F</ContentIdOverride>
    <EKBIDOverride>00000000-0000-0000-0000-000000000001</EKBIDOverride>
  </DevelopmentOnly>

8、后台生成证书不要选择沙盒