整体操作步骤
魔方 H5 支持对接 App、小程序的登录态，需要完成 4 个步骤

1. App 的提供生成 Token 的能力，通过 JSB 注入到 WebView 中 —— 由客户方 App 研发完成。
2. 在 SDK.js 中实现 getAccessToken 方法，对接 JSB —— 由客户方前端研发完成。
3. 提供 Token 获取用户信息的接口（需要确保接口在魔方服务器能访问） —— 由客户方后端研发完成。
4. 魔方平台中配置 —— 由客户方平台使用者完成：
   1. 在集成中心配置接口。
   2. 应用管理中上传 SDK.js (小程序场景不需要)，选择接口。

1 整体数据交互

在 App/小程序 打开魔方 H5，根据登录状态可分为两个阶段：
阶段一：​App/小程序 未登录阶段：H5 会触发打开 App/小程序 的登录页面（如果能确保打开 H5 时，App 已登录，则忽略此阶段）。
阶段二：​App/小程序 已登录阶段：H5 会通过 Token 对接的方式，获取到 App/小程序 中登录的用户信息。

具体的数据交互参考下图，需要客户侧提供 3 个方面的支持：

其中 2、3 是需要重点关注的，下方文档有详细说明，完成这两步后即完成了登录态的对接。

2 SDK.js

不同的 App 注入的 JSB 可能不太一样，所以需要 SDK.js 作为中间层抹平这些差异，提供统一的方法供 H5 调用。
小程序无法注入 JSB，可以考虑通过 Url 传递 Token，下方有详细说明。

2.1 开发

SDK.js 将在 H5 中直接加载，不会经过编译，请避免写入敏感信息、浏览器无法执行的 JS 语法。

// SDK.js 的 ts 类型说明
interface AccessTokenResult {
  statusCode: number;  // 返回码 0：成功，-1：失败
  data: {
    access_token: string; // 具体的 Token
  }
 }
 
 interface MagicJSBridge {
  // 打开 App 登录页 
  openLogin: () => void
  
  // 获取登录 Token
  // 具体实现是异步获取的话，可以返回 Promise
  getAccessToken: () => AccessTokenResult | Promise<AccessTokenResult>;
}
 

示例

window.MagicJSBridge = {
  openLogin() {
    // 替换成业务自己的弹出登录框/跳转登录页面逻辑
    alert('弹出登录框')
  },
  getAccessToken() {
    // 替换成业务自己的获取 token 逻辑
    // 支持返回 Promise
    return Promise.resolve({
      statusCode: 0,
      data: {
        access_token: 'your token'
      }
    })
  },
}

    

小程序特别说明
小程序嵌入 H5，小程序与 H5 通信比较复杂，可以考虑在打开 H5 时，将 Token 添加在 H5 Url 中，SDK.js 中在 Url 中获取。示例：

window.MagicJSBridge = {
  getAccessToken() {
    // Url 类似 http://a.com/xxxxxx?token=xxxxxxx
    const key = 'token' // 参数名可自定义
    const h5url = new URL(location.href)
    if (h5url.searchParams.has(key)) {
      const token = h5url.searchParams.get(key);
      // （重要）清除 Url 中的 Token，避免分享了带 Token 的地址
      // 同时，建议 Token 有时效性，避免泄露 Token 后越权登录
      h5url.searchParams.delete(key);
      history.replaceState({}, '', h5url.toString());
      
      // 返回 Token
      if (token) {
        return {
          statusCode: 0,
          data: {
            access_token: token
          }
        }
      }
    }
    
    return {
      statusCode: -1,
      data: {}
    }
  }
}

2.2 上传

在 活动落地页 -> 应用管理页面，创建/编辑应用时，上传这个 SDK.js。之后在创建 H5 时关联该应用，则会加载、执行这个 SDK。

3 用户信息接口

客户侧 Server 需要提供一个接口，传入Token，返回用户信息，魔方 Server 将调用这个接口。
一些场景的说明：

1. 如果是新开发的的接口，建议按照我们的标准接口开发。
2. 如果是现有接口，可以在 “接口配置” 中将现有接口的格式，通过配置转为标准接口
3. 如果接口有校验机制的话（比如 aksk 校验），可以在 “接口配置” 中，通过 JS 脚本处理

3.1 标准接口定义

请求字段

响应字段

data 字段结构

JSON 示例

// POST 方法请求
// 1. 传入数据
{
   access_token: 'my token'; // SDK 中 MagicJSBridge.getAccessToken 返回的 access_token
}

// 2. 返回用户信息
{
    statusCode: 0; // 0: 成功 其他: 失败
    message: '';
    data: {
        uid: '1000001'; // 用户身份 id，最重要
        username: '用户1'; // 用户名称（可选字段）
        avatar?: 'http://a.com/b.png'; // 用户头像（可选字段）
        extra: {
            // 可拓展透传其他字段（可选字段）
            id_list: [{
                user_id: '11111', // id 值
                id_type: 'did' // id 类型
            }]
        }
    }
}

3.2 接口 Webhook 配置

Webhook 是 GMP 的一个通用化对接能力。
调用外部接口时，可以对请求地址、鉴权方式、HTTP方法、完整的请求参数以及请求响应解析规则进行配置。具有较高的通用性。同时，允许自定义请求处理脚本、自定义响应处理脚本，可自行适配接口的认证机制。
细节可参考【外部 v3.12-v4.1】GMP通用Webhook对接

不同的魔方版本，配置的方法不同，先在页面中查看版本

3.2.1 v5.11+ 版本

配置页面路径: 管理中心 -> 集成中心

点击「创建业务」，填写必要信息，模版选择「魔方-C端登录系统对接」

编辑「集成流程」中的「拉取用户信息」节点，填写必要信息

3.2.2 v5.9- 版本

配置页面路径: 管理中心 -> 魔方接口 -> C端用户登录态

配置接口
我们提供了一份标准的配置，可以导入后，根据实际情况修改接口路径、字段配置、处理脚本等。

token模式登录接口配置：

[{"InterfaceId":10110,"CustomCallSuite":{"BasicCustomCallConfig":{"TargetUrl":"https://gmp-saas-stage-api.console.volcengine.com/gmpb/magic/openapi/playing/customer/tokenLoginSimulation","Method":1,"BodyConfig":{"ContentType":1,"BodyParams":[{"ParamName":"access_token","ParamType":25,"Value":"$.access_token","IsRequire":false}],"JsonBody":"{\n  \"access_token\": \"${access_token}\",\n  \"clientSecret\":\"zyh_test\",\n    \"gmp_test_uid\":\"123\",\n    \"gmp_test_user_name\":\"123\"\n}"},"RespJudgeConfig":{"SuccessRules":[{"HttpStatus":200,"JsonPath":"$.code","Operator":1,"Value":"0","ShouldRetry":false}],"FailRules":[{"JsonPath":"$.code","Operator":2,"Value":"0","ShouldRetry":false}]},"CustomCallType":1,"HttpReqConfig":{"TargetUrl":"https://gmp-saas-stage-api.console.volcengine.com/gmpb/magic/openapi/playing/customer/tokenLoginSimulation","Method":1,"BodyConfig":{"ContentType":1,"BodyParams":[{"ParamName":"access_token","ParamType":25,"Value":"$.access_token","IsRequire":false}],"JsonBody":"{\n  \"access_token\": \"${access_token}\",\n  \"clientSecret\":\"zyh_test\",\n    \"gmp_test_uid\":\"123\",\n    \"gmp_test_user_name\":\"123\"\n}"},"RespJudgeConfig":{"SuccessRules":[{"HttpStatus":200,"JsonPath":"$.code","Operator":1,"Value":"0","ShouldRetry":false}],"FailRules":[{"JsonPath":"$.code","Operator":2,"Value":"0","ShouldRetry":false}]}},"RetryForDownStreamErr":false,"MaxRetryCount":3,"TimeoutMs":3000,"QpsLimit":100},"ConcernInfoConfigs":[{"Key":"code","JsonType":2,"JsonPath":"$.code"},{"Key":"message","JsonType":1,"JsonPath":"$.msg"},{"Key":"uid","JsonType":1,"JsonPath":"$.data.uid"},{"Key":"user_name","JsonType":1,"JsonPath":"$.data.username"},{"Key":"avatar","JsonType":1,"JsonPath":"$.data.avatar"},{"Key":"extra","JsonType":1,"JsonPath":"$.data.extra"}]},"Name":"模拟客户token登录接口","Type":1,"ModuleTag":"magic_thirdparty_userinfo","InterfaceType":"magic_login_with_token_cookies","Status":1,"Creator":"saas_test_cdp_2","Updater":"saas_test_cdp_2","CreatedAt":1696981769,"UpdatedAt":1696981782,"Platform":"default","ListDisplayConfig":{"DisplayConfigList":null,"ArrayJsonPath":"","CountJsonPath":""},"SupportBatch":0,"AsyncSwitch":0,"AsyncConfig":{"AsyncIsBatchResp":0,"AsyncMsgIdType":0,"AsyncUpChannelId":0}}]

4 常见问题

4.1 如何进行调试

对接完后，可新建一个活动，通过测试链接访问（即地址路径带 beta 的），点击右下角的 ⚙️，类似浏览器中的 F12，可查看 console 和 network 信息。

预览地址获取方式：
活动列表页找到对应活动 -> 点击编辑进入编辑页 -> 点击右上角的预览 -> 点击获取测试链接

可重点关注 2 个节点

1. 是否获取到了 Token
2. login 请求的参数和返回数据

4.2 页面没执行 getAccessToken

建议检查 console 中是否有 SDK.js 报错信息，是否有 App Webiew 无法执行的 JS 语法，比如 ES6、ES7 语法。

4.3 Login 接口返回错误

// 错误码对应关系
-14701 // 魔方应用未配置登录 webhook
-14702 // webhook调用错误，1. webhook 开关没打开；2. webhook 配置的接口从魔方 Server 无法访问
-14703 // 登录认证服务异常，webhook 配置的接口返回了异常数据
-14704 // token解析失败

魔方 H5 支持对接 App 的分享能力，需要做三部分的工作：

1. App 的分享能力，通过 JSB 注入到 WebView 中 —— 由 App 研发完成
2. 在 SDK.js 中实现 share 方法，对接 JSB —— 由前端研发完成
3. 活动搭建时，配置分享信息 + 使用分享组件 —— 由运营人员完成

调用链路如下

1 SDK.js 实现 share 方法

share 方法的类型

interface ShareParams {
  // 1. 页面分享信息
  link: string; // 当前页面地址
  title: string; // 当前页面标题
  desc: string; // 当前页面描述
  
  // 2. 当前用户信息 + 活动信息
  user: {
    uid?: string;
    username?: string;
    avatar?: string;
  };
  appId: string; // 活动绑定的应用Id
  activityId: string; // 活动Id
  
  // 3. 玩法 + 任务信息
  playRuleId?: string; // 玩法Id，分享任务组件才有
  taskId?: string; // 任务Id，分享任务组件才有
}

interface MagicJSBridge {  
  // 分享
  share: (params: ShareParams) => boolean | void;
}

代码示例

window.MagicJSBridge = {
  share(params) {
    // 替换成业务自己的分享逻辑
    console.log('MagicJSBridge.share', params)
    alert('分享')
  }
}

2 活动配置分享信息

在活动编辑页面，配置活动分享信息，包括标题、描述、图片，这些信息将会传入 share 方法
分享的卡片样式仅供参考，最终效果取决于分享发起方和分享目标渠道

搭建页面时，使用分享按钮组件，并且分享方式选择「端内分享+海报兜底」，用户点击该按钮，将会唤起 App 分享能力

魔方 H5 支持在浏览器唤起 App，并定位到活动页，需要完成 3 个步骤：

1. 魔方应用中配置 UA
2. 在 SDK.js 中实现 getSchemeAndLink 方法
3. App 支持读取 scheme 信息，打开活动页

调用链路如下

1 魔方应用中配置 UA

魔方应用中配置 UA，配置为 App 打开 WebView 时，在 User-Agent 中设置的特殊字符串（需要适配多个 App 时，可填写正则字符串），有2 个途径获取特殊字符串：

1. 由 App 研发提供。
2. 在 App 内打开魔方 H5 的预览地址，在调试面板中，查看 App 的 User-Agent，再判断一下哪一段是特殊字符串。

以微信为例，可以判断出来，微信的 UA 可配置为 MicroMessenger 。

2 SDK.js 实现 getSchemeAndLink 方法

用于端外访问H5时，自定义跳转端内的地址，可返回2个地址：

1. scheme（可选），返回 App 的 URL scheme，返回则尝试使用 scheme 唤起 App（需要 App 支持 deeplink，拉起后打开魔方 H5）
2. link，返回页面地址，一般为 App 落地页/下载页，客户可在该页面实现唤起 App 的逻辑

方法类型：

interface MagicJSBridge {
  // 获取跳转App地址
  getSchemeAndLink?: () => {
    // 跳转页面地址
    link: string;  
    // App scheme，有值的话会尝试调起，微信内不支持  
    scheme?: string;
  }
}

代码示例

window.MagicJSBridge = {
  getSchemeAndLink() {
    // 替换成业务自己的 getSchemeAndLink 逻辑
    return {
      link: 'https://weixin.qq.com',
      scheme: 'weixin://'
    }
  }
}

魔方 H5 支持 2 中维度的埋点定制化：

1. 支持在上报数据中的增加字段
2. 支持将数据上报到三方系统

1 增加事件属性

现有事件属性可参考 魔方toB埋点事件-属性（对外版），如果需要增加属性，通过以下步骤增加

注意：区分渠道数据场景

默认埋点属性中，source 字段是为投放渠道预留的字段，需要的话可直接使用，不需要再增加属性
设置方法

1. 投放时，在活动 Url 中增加 magic_source 参数，例如 https://magic.com/magic/eco/runtime/beta/64xxxxxxx?magic_source=banner_1
2. 实现 getFinderEventData 方法，设置 source 字段，参考下方 1.2.1

实现效果

1.1 数分系统增加属性

一般而言，数分系统不会接收任意属性，需要在后台配置。以 Finder v4.9.0 为例：（需要采购 Finder）
在 数据管理 ->元数据管理 -> 事件属性 -> 新建用户属性 中新建属性。
新建为 公共属性，或者 关联上魔方事件（需要在哪个事件中增加属性，则关联哪个，可多选）

三方系统也是类似操作，确保属性上报后，系统会进行接收存储。

1.2 事件上报中增加属性

魔方提供 2 种方式增加属性

1.2.1 SDK 方式

修改 应用管理 的 SDK.js，实现 getFinderEventData，进行定制化上报数据。

window.MagicJSBridge = {
  // ...

  getFinderEventData(originData) {
    // 增加属性
    originData.custom_prop_a = 'some value'
    
    // 同时，支持修改原有属性
    originData.old_prop_a = 'some value'
    
    // 需要注意，如果使用 Finder 上报 + 修改公共属性的话，需要额外设置
    window.collectEvent('config', {evtParams: {common_prop_a: 'some value'}})
    // 公共属性包括：activityId, productUId, applicationId, app_id, project_id, 
    // language, osType, logCode, source, activityVersion, magicVersion, location, channel, h5url
    
    return originData
  }  

  // ...
}

1.2.2 URL 方式

通过 URL 传到 event_params 参数增加属性，需要对参数值进行 JSON 序列化 + Base64 处理。

// 以浏览器中的 JS 环境为例

// 1. 需要增加的属性
const props = {
  custom_prop_a: 'some value'
}

// 2. JSON 序列化
const json = JSON.stringify(props)
// {"custom_prop_a":"some value"}

// 3. Base64处理
const value = btoa(json)
// eyJjdXN0b21fcHJvcF9hIjoic29tZSB2YWx1ZSJ9

// 4. 拼接 H5 URL
const url = 'https://a.com/magic/eco/runtime/release/6673f62ce9e36400202fdffd?event_params=' + value

2 上报到三方系统

修改 应用管理 的 SDK.js，实现 sendLog，将魔方埋点数据上报到三方系统。

// 1. 将三方系统的上报 SDK 代码粘贴进来


window.MagicJSBridge = {
  // ...
  
  // 2. 实现 sendLog 方法
  // 页面的埋点数据，将调用这个方法上报
  sendLog(data) {
    console.log('事件名', data.event)
    console.log('事件数据', data.params)
    // 3. 这里调用三方 SDK 的上报方法
  }
  
  // ...
}

1 微信分享卡片样式

页面分享的卡片展示效果，最终由分享的源平台 + 分享的目标平台决定的，魔方系统无法决定。
对于微信的分享卡片展示效果：

1. 微信打开H5分享到微信，效果是只有标题
2. 微信打开H5，点击收藏，从收藏分享到微信，效果是有图片 + 标题
3. iOS Chrome 打开H5，分享到微信，效果是有图片 + 标题 + 描述

2 微信中关闭 H5

场景
在微信中扫码、点击链接打开魔方H5，点击页面按钮关闭H5
实现
在按钮中「编辑交互动作」，配置如下

window.WeixinJSBridge && window.WeixinJSBridge.call('closeWindow')

3 微信小程序打开/关闭 H5

3.1 打开 H5

1. 域名开白：需要在微信小程序后台对域名开白（如果H5需要对接微信帐号，额外需要对 https://gmp.bytedanceapi.com 开白）
2. 页面嵌入：在 page 中使用小程序的 web-view 组件展示 H5

<view>
  <!-- url 为 H5 的地址 -->
  <web-view src="{{url}}" />
</view>

3.2 关闭 H5

可在 H5 使用 weixin sdk 进行自关闭，以点击按钮关闭为例。
在按钮中「编辑交互动作」进行配置

1. 组件加载：加载 weixin sdk （如果按钮在弹窗中，建议在页面中的任意常显的文本、图片、按钮组件添加组件加载事件）

const $s = document.createElement('script')
$s.setAttribute('src', 'https://res.wx.qq.com/open/js/jweixin-1.6.0.js')
window.oldDefine = window.define
window.define = null
document.head.appendChild($s)
setTimeout(() => {
  window.define = window.oldDefine
}, 1000)

2. 单击事件：执行回退操作

// 关闭 H5
wx.miniProgram.navigateBack({
    success: (res) => {
        console.log('success', res)
    },
    fail: (err) => {
        console.log('fail', err)
    }
})

// 跳转到其他页面
wx.miniProgram.navigateTo({
    // 小程序页面路径
    url: '/pages/index/index',
    success: (res) => {
        console.log('success', res)
    },
    fail: (err) => {
        console.log('fail', err)
    }
})

更多功能参考微信的sdk文档 https://developers.weixin.qq.com/miniprogram/en/dev/api/route/wx.switchTab.html

4 H5 唤起微信小程序

场景
H5 中点击按钮，跳转到微信小程序制定页面
实现
在按钮中「编辑交互动作」，配置如下

跳转链接说明
跳转链接为小程序明文 scheme，相关文档
https://developers.weixin.qq.com/miniprogram/dev/framework/open-ability/url-scheme.html

格式
weixin://dl/business/?appid=*APPID*&path=*PATH*&query=*QUERY*&env_version=ENV_VERSION

示例
weixin://dl/business/?appid=wxbee437cfe27aec05&path=pages/index/index

需要注意，跳转的 path 需要配置加白，才能跳转成功

1 魔方应用的配置说明

2 完整的 SDK.js 说明

魔方 H5 通过该 SDK，对接 App 的各项能力

window.MagicJSBridge = {
  openLogin() {
    // 替换成业务自己的弹出登录框/跳转登录页面逻辑
    alert('弹出登录框')
  },
  share(params) {
    // 替换成业务自己的分享逻辑
    console.log('MagicJSBridge.share', params)
    alert('分享')
  },
  getAccessToken() {
    // 替换成业务自己的获取 token 逻辑
    // 支持返回 Promise
    return Promise.resolve({
      statusCode: 0,
      data: {
        access_token: 'your token'
      }
    })
  },
  getSchemeAndLink() {
    // 替换成业务自己的 getSchemeAndLink 逻辑
    return {
      link: 'https://weixin.qq.com',
      scheme: 'weixin://'
    }
  },
  getFinderInitOptions(options) {
    // 修改 finder 初始化参数，使用火山的 finder 埋点系统才有效
    options.disable_auto_pv = true
    return options
  },
  getFinderEventData(eventData) {
    // 修改 finder 埋点数据，使用火山的 finder 埋点系统才有效
    eventData.aaa = 1
    return eventData
  }
  // 页面的埋点数据，将调用这个方法上报
  sendLog(data) {
    console.log('事件名', data.event)
    console.log('事件数据', data.params)
    // 这里调用三方 SDK 的上报方法
  }
}