ZOLOZZOLOZDOCS

initialize

概览

  • API URL：/api/v1/zoloz/location/initialize
  • API 描述：该接口用于初始化定位检测流程。

说明：

  • 调用GeoTrust Locator API前，请确保客户端已集成定位检测功能相关SDK，详见客户端接入流程。
  • 该接口不支持重复调用，即不符合幂等性。

请求参数

字段名称

数据类型

最大长度

是否必填

默认值

描述

示例值

bizId

String

32


是

-

业务ID，业务的唯一标识，用于追踪业务。例如，商户业务相关数据库中的序列号。

说明：ZOLOZ服务器不检查该字段的值是否唯一。为了更便捷地追踪业务，建议开启商户服务器，并确保业务ID的唯一性。

"2017839040588699"

metaInfo

String

512

是

-

SDK和用户设备的元信息。该字段的值由ZOLOZ SDK以JSON字符串格式返回。

说明：不要修改返回值，直接传递即可。如果是H5接入模式，则设置为MOB_H5。

{

"deviceType": "android",

"appVersion": "1.0.9",

"osVersion": "9",

"appName": "com.zoloz.atomic.client",

"bioMetaInfo": "3.46.0:2916352,0",

"apdidToken": "69b74bfe-bf7f-4d3b-ac59-907ee09e****",

"deviceModel": "MI 6",

"zimVer": "1.0.0"

}

userId

String

64

是

-

商户的用户ID或其他可用于识别某一用户的标识，例如手机号码、电子邮件地址等。

建议对userId字段的值进行预脱敏，例如进行哈希处理。

"123456abcd"

detectMock

Boolean

-

否

true

是否开启模拟定位检测。开启后可检测用户是否使用模拟定位软件伪造所在位置。取值：

  • true：开启检测。
  • false：关闭检测。

true

detectVpn

Boolean

-

否

true

是否开启VPN连接检测。开启后可检测用户是否通过VPN连接网络。取值：

  • true：开启检测。
  • false：关闭检测。

true

geoFenceMatch

List

-

否

-

地理围栏匹配列表，用于验证用户实际位置是否在指定的行政区范围内。

  • 支持传一个或多个行政区编码，目前仅支持：
    • HK：中国香港
    • MO：中国澳门
  • 不传或传空数组，表示不开启地理围栏检测功能。

["HK", "MO"]

返回参数

字段名称

数据类型

必须返回

描述

示例值

result

Result

是

API请求结果，包含结果状态、结果码和结果消息。

{

"resultStatus": "S", "resultCode": "SUCCESS", "resultMessage": "Success"

}

transactionId

String

否

ZOLOZ服务器为定位检测流程生成的唯一事务ID。此ID将作为GeoTrust Locator checkresult API请求的输入参数。

说明：仅当交易进入处理阶段后系统才会返回transactionId。如果在开始处理交易之前发生错误，系统不会返回transactionId。包括但不限于以下情况：

  • 请求参数非法，例如入参格式错误或缺失必传参数。
  • 请求未能成功到达服务器，例如网络问题或网关故障。
  • 系统限流导致请求被拒绝。

"G000000005FID2020030400000000000157****"

clientCfg

String

否

客户端配置信息，SDK将使用该配置进行后续操作。请将返回值原样传递给客户端SDK。

说明：仅当result.resultStatus的值为S时才返回该字段。

"{...}"

处理结果

根据请求结果执行下一步的响应动作，具体如下：

  • 当result.resultStatus的值为S时，表示调用ZOLOZ GeoTrust Locator initialize API成功，并返回唯一的事务ID。
  • 当result.resultStatus的值为F时，表示调用ZOLOZ GeoTrust Locator initialize API失败。请检查错误码获取有关该错误的更多信息，并分析导致该错误的原因。

API通用结果码

有关通用结果码的完整列表，请参见API通用结果码。

API特有结果码

GeoTrust Locator initialize API的结果码见下表。

结果码

结果状态

描述

SUCCESS

S

API调用成功。

HIGH_RISK

F

检测到高风险，用户账号被风险引擎冻结。

ACCOUNT_SERVICE_SUSPEND

F

用户账号被风险引擎列入黑名单。

DEVICE_NOT_SUPPORT

F

不支持当前的设备类型。

OS_NOT_SUPPORT

F

不支持当前设备的操作系统。

INVALID_ARGUMENT

F

输入参数无效。关于无效参数的详细信息，请查看返回的resultMessage。

SYSTEM_ERROR

F

其他内部错误。有关错误详情，请查看返回的resultMessage。

METAINFO_NOT_SUPPORT

F

客户端版本不支持定位功能，MetaInfo第57位版本小于1。

INVALID_PARAM

F

请求参数错误。

UNKNOWN

F

未分类系统错误。

CONFIG_EMPTY

F

定位配置内容为空。

代码示例

请求示例

copy
{
    "bizId": "2017839040588699", 
    "metaInfo": "{\"deviceType\":\"android\",\"appVersion\":\"1.0.9\",\"osVersion\":\"9\",\"appName\":\"com.zoloz.atomic.client\",\"bioMetaInfo\":\"3.46.0:2916352,0\",\"apdidToken\":\"69b74bfe-bf7f-4d3b-ac59-907ee09e****\",\"deviceModel\":\"MI 6\",\"zimVer\":\"1.0.0\"}", 
    "userId": "user_123456", 
    "detectMock": true, 
    "detectVpn": true, 
    "geoFenceMatch": [
        "HK", 
        "MO"
    ]
}

返回示例

copy
{
    "result": {
        "resultStatus": "S", 
        "resultCode": "SUCCESS", 
        "resultMessage": "Success"
    }, 
    "transactionId": "G000000005FID2020030400000000000157****", 
    "clientCfg": "{\"protocol\":{\"timestamp\":\"1634567890123\",\"signature\":\"xxxxx\"}}"
}