10/27/2025 18:02:31

位置模块

一、概述

位置模块（ Location Based Service, LBS ）, 主要为业务提供相关玩家位置的功能。如，玩家可以获取当前位置，获取附近好友，清除位置设定，查询当前 IP 所处国家。使用 LBS 功能尽量避免短时间内频繁调用。

位置模块“获取 IP 对应位置信息”接口，支持国内和海外且无需登录。剩余接口，均仅支持国内 QQ、Wechat 登录。

二、接入向导

推荐接入 MSDK LBS 位置服务流程：

注册 MSDK LBS 回调
调用 MSDK LBS 功能

接入 MSDK LBS 位置服务需要：

已经按初始化模块说明完成 MSDK 初始化
调用 MSDK LBS 接口需要先登录

2.1 配置说明

1）Android 配置

Android 平台 MSDK LBS 定位依赖 support-v4 库，记得检查游戏的工程是否引入 support-v4 及 support-v4 的依赖。 MSDK 使用 support-v4-26.1.0 依赖版本：
- support-compat-26.1.0
- support-core-ui-26.1.0
- support-core-utils-26.1.0
- support-fragment-26.1.0
- support-media-compat-26.1.0
- support-v4-26.1.0
【可选项】配置 MSDK 环境，字段 MSDK_LBS_GPS_TIMEOUT，表示设置 GPS 定位超时时间（无配置，默认 4s）。
Android 还需要配置权限和权限申请窗口注册（ AndroidManifest.xml 文件中），如下：

//权限声明
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

<application>
    ......
    // 动态权限申请窗口注册
    <activity android:name="com.tencent.gcloud.msdk.lbs.PermissionActivity"/>

</application>

2）iOS 配置

iOS 平台依赖系统库文件：CoreLocation.framework
iOS 配置申请定位权限时对用户的提示说明，Xcode 工程配置文件 info.pilst添加

<key>NSLocationWhenInUseUsageDescription</key>
    <string>CurrentNeedLocation</string>

CurrentNeedLocation，申请定位权限时对用户的提示说明

[warning] LBS 注意项
使用 LBS 功能必须添加该配置项，否则有被拒风险，且可能导致 LBS 功能使用异常

2.2 注册回调

1）功能描述

为了接收 MSDK LBS 模块的回调，游戏需要首先注册回调函数。

2）接口声明

C++

// 获取位置信息回调
public static event OnMSDKRetEventHandler<MSDKLBSLocationRet> LBSLocationRetEvent;

// 获取附近的人列表回调
public static event OnMSDKRetEventHandler<MSDKLBSRelationRet> LBSRelationRetEvent;

// 获取 IP 信息列表
public static event OnMSDKRetEventHandler<MSDKLBSIPInfoRet> LBSIPInfoRetEvent;

// 清除位置信息回调
public static event OnMSDKRetEventHandler<MSDKBaseRet> LBSRetEvent;

class MSDKLBSObserver
{
public:
    //新增一个虚析构函数 不然 UnrealEngine 报错
    virtual ~MSDKLBSObserver(){};

    // 获取位置信息回调
    virtual void OnLBSLocationRetNotify(const MSDKLBSLocationRet &locationRet) {};

    // 获取附近的人回调
    virtual void OnLBSRelationRetNotify(const MSDKLBSRelationRet &relationRet) {};

    // 获取 IP 信息回调
    virtual void OnLBSIPInfoRetNotify(const MSDKLBSIPInfoRet &ipInfoRet) {};

    // 基础回调：清除位置信息回调
    virtual void OnLBSBaseRetNotify(const MSDKBaseRet &baseRet) {};
};

3）示例代码

C++

MSDKLBS.LBSRetEvent += mLBSCallBack.OnLBSClearLocationEvent;
MSDKLBS.LBSLocationRetEvent += mLBSCallBack.OnLBSGetLocationEvent;
MSDKLBS.LBSIPInfoRetEvent += mLBSCallBack.OnLBSGetIpInfoEvent;
MSDKLBS.LBSRelationRetEvent += mLBSCallBack.OnLBSGetNearByEvent;

public void OnLBSGetLocationEvent(MSDKLBSLocationRet baseRet)
{
    string methodTag = "MSDKLBSLocationRet";

    // SampleInstance.showRetDialog (methodTag, webViewRet);
    mCurrentTestMgr.ShowLogInNewLine(methodTag + Tools.Instance.GetRetString(baseRet));
}

public void OnLBSGetNearByEvent(MSDKLBSRelationRet lbsRelationRet)
{
    string methodTag = "MSDKLBSRelationRet";

    // SampleInstance.showRetDialog (methodTag, webViewRet);
    mCurrentTestMgr.ShowLogInNewLine(methodTag + Tools.Instance.GetRetString(lbsRelationRet));
}

public void OnLBSClearLocationEvent(MSDKBaseRet baseRet)
{
    string methodTag = "ClearLocationInfo";

    // SampleInstance.showRetDialog (methodTag, webViewRet);
    mCurrentTestMgr.ShowLogInNewLine(methodTag + Tools.Instance.GetRetString(baseRet));
}

public void OnLBSGetIpInfoEvent(MSDKLBSIPInfoRet lbsIpInfoRet)
{
    string methodTag = "MSDKLBSIPInfoRet";

    // SampleInstance.showRetDialog (methodTag, webViewRet);
    mCurrentTestMgr.ShowLogInNewLine(methodTag + Tools.Instance.GetRetString(lbsIpInfoRet));
}

MSDKLBS::SetLBSObserver(new MSDKLBSCallBacks());

#if PLATFORM_IOS || PLATFORM_ANDROID
using namespace GCloud::MSDK;
class CLIENTUETEST_API MSDKLBSCallBacks : public MSDKBaseCallBacks, public MSDKLBSObserver
{
public:

    MSDKLBSCallBacks();

    virtual ~MSDKLBSCallBacks();

    // 获取位置信息回调
    virtual void OnLBSLocationRetNotify(const MSDKLBSLocationRet &locationRet);
    // 获取附近的人回调
    virtual void OnLBSRelationRetNotify(const MSDKLBSRelationRet &relationRet);

    // 获取 IP 信息回调
    virtual void OnLBSIPInfoRetNotify(const MSDKLBSIPInfoRet &ipInfoRet);
    // 基础回调：清除位置信息回调
    virtual void OnLBSBaseRetNotify(const MSDKBaseRet &baseRet);

};
#else

class CLIENTUETEST_API MSDKLBSCallBacks : public MSDKBaseCallBacks
{
public:
    MSDKLBSCallBacks();

    ~MSDKLBSCallBacks();

};

#endif

4）数据结构

获取位置回调结构：MSDKLBSLocationRet 详解
继承自 MSDKBaseRet，包含的数据字段

成员变量名称	类型	说明
longitude	double	经度
latitude	double	纬度

获取附近玩家回调结构：MSDKLBSRelationRet 详解
继承自 MSDKBaseRet，包含的数据字段

成员变量名称	类型	说明
isLost	string	后台是否对数据降级处理，特殊渠道有，一般无须关心
personList	List	附近玩家列表，最多可获取70-80人

其中，玩家列表字段: MSDKPersonInfo 继承自 MSDKPersonInfo

获取 IP 对应位置信息回调结构：MSDKLBSIPInfoRet 详解
继承自 MSDKBaseRet，包含的数据字段

成员变量名称	类型	说明
country	string	IP 对应的 ISO_3166-1标准中的国家或地区中文名称
countryCode	int	国家或地区编码
province	string	省级名称，限制中国大陆区域使用
provinceCode	int	预留字段，省级编码，限制中国大陆区域使用
city	string	市级名称，限制中国大陆区域使用
cityCode	int	预留字段，市级编码，限制中国大陆区域使用
timestamp	long	时间戳
isByHeader	bool	查询方式，是通过查询缓存或请求头中获取，一般无须关心

清除位置信息回调结构：MSDKBaseRet

2.3 获取位置

1）功能描述

调用该接口，可通过基站定位、WIFI 定位、GPS 定位（任何一种定位成功即可）得到玩家的位置信息，返回玩家当前的经纬度。建议 Android 工程中加上 ACCESS_WIFI_STATE 非敏感权限。
该接口仅支持国内。

2）接口调用

C++

// MSDK LBS 获取位置接口
void GetLocation();

// MSDK LBS 获取位置接口
void GetLocation();

3）回调接口

C++

// MSDK LBS 获取位置回调
public void OnLBSGetLocationEvent(MSDKLBSLocationRet baseRet);

// 获取位置信息回调
void OnLBSLocationRetNotify(const MSDKLBSLocationRet &locationRet);

4）示例代码

C++

public void GetLocation()
{
    MSDKLBS.GetLocation ();
}

void TestModuleMSDKLBS::GetLocation()
{
    UE_LOG(LogTemp, Warning, TEXT("GetLocation"));
#if PLATFORM_IOS || PLATFORM_ANDROID
    MSDKBaseTestManager::Instance()->ShowLogInNewLine("GetLocation");
    MSDKLBS::GetLocation();
#else
    UE_LOG(LogTemp, Warning, TEXT("no support GetLocation"));
#endif
}

2.4 获取附近玩家

1）功能描述

可获取到玩家附近位置的其他已定位玩家列表。
该接口仅支持国内。

2）接口调用

C++

// MSDK LBS 获取附近玩家接口
void GetNearby();

// MSDK LBS 获取附近玩家接口
void GetNearby();

3）回调接口

C++

// MSDK LBS 获取附近玩家回调
public void OnLBSGetNearByEvent(MSDKLBSRelationRet lbsRelationRet);

// 获取附近的人回调
void OnLBSRelationRetNotify(const MSDKLBSRelationRet &relationRet);

4）示例代码

C++

public void GetNearby()
{
    MSDKLBS.GetNearby ();
}

void TestModuleMSDKLBS::GetNearby()
{
    UE_LOG(LogTemp, Warning, TEXT("GetNearby"));
#if PLATFORM_IOS || PLATFORM_ANDROID
    MSDKBaseTestManager::Instance()->ShowLogInNewLine("GetNearby");
    MSDKLBS::GetNearby();
#else
    UE_LOG(LogTemp, Warning, TEXT("no support GetNearby"));
#endif
}

2.5 清除位置信息

1）功能描述

在获取位置和获取附近好友功能中，都会设置玩家的信息到后台。调用该接口可清除后台对该玩家的位置设置，使得该玩家不会出现在别的玩家的附近玩家列表中。
该接口仅支持国内。

2）接口调用

C++

// MSDK LBS 清除位置接口
void ClearLocation();

// MSDK LBS 清除位置接口
void ClearLocation();

3）回调接口

C++

// MSDK LBS 清除位置回调
public void OnLBSClearLocationEvent(MSDKBaseRet baseRet);

void OnLBSBaseRetNotify(const MSDKBaseRet &baseRet);

4）示例代码

C++

public void ClearLocationInfo()
{
    MSDKLBS.ClearLocation ();
}

void TestModuleMSDKLBS::ClearLocation()
{
    UE_LOG(LogTemp, Warning, TEXT("ClearLocation"));
#if PLATFORM_IOS || PLATFORM_ANDROID
    MSDKBaseTestManager::Instance()->ShowLogInNewLine("ClearLocation");
    MSDKLBS::ClearLocation();
#else
    UE_LOG(LogTemp, Warning, TEXT("no support ClearLocation"));

#endif
}

2.6 获取 IP 对应位置信息

1）功能描述

当前设备网络的 IP 地址对应位置信息。当前可以提供国家、省、市信息，其中省、市从 MSDKV5.28 版本开始支持，建议海外区域仅使用国家。

2）接口调用

C++

// MSDK LBS 获取 IP 对应位置信息接口
void GetIPInfo();

// MSDK LBS 获取 IP 对应位置信息接口
void GetIPInfo();

3）回调接口

C++

// MSDK LBS 获取 IP 对应位置信息回调
public void OnLBSGetIpInfoEvent(MSDKLBSIPInfoRet lbsIpInfoRet);

// 获取 IP 信息回调
void OnLBSIPInfoRetNotify(const MSDKLBSIPInfoRet &ipInfoRet);

获取 IP 对应位置信息回调结构：MSDKLBSIPInfoRet 详解
继承自 MSDKBaseRet，包含的数据字段

成员变量名称	类型	说明
country	string	IP 对应的 ISO_3166-1标准中的国家或地区中文名称
countryCode	int	国家或地区编码
province	string	省级名称，限制中国大陆区域使用
provinceCode	int	预留字段，省级编码，限制中国大陆区域使用
city	string	市级名称，限制中国大陆区域使用
cityCode	int	预留字段，市级编码，限制中国大陆区域使用
timestamp	long	时间戳
isByHeader	bool	查询方式，是通过查询缓存或请求头中获取，一般无须关心

4）示例代码

C++

public void GetIPInfo()
{
    MSDKLBS.GetIPInfo ();
}

void TestModuleMSDKLBS::GetIPInfo()
{
    UE_LOG(LogTemp, Warning, TEXT("GetIPInfo"));
#if PLATFORM_IOS || PLATFORM_ANDROID
    MSDKBaseTestManager::Instance()->ShowLogInNewLine("GetIPInfo");
    MSDKLBS::GetIPInfo();
#else
    UE_LOG(LogTemp, Warning, TEXT("no support GetIPInfo"));

#endif
}

位置模块

位置模块

一、概述

二、接入向导

2.1 配置说明

2.2 注册回调

2.3 获取位置

2.4 获取附近玩家

2.5 清除位置信息

2.6 获取 IP 对应位置信息

results matching ""

No results matching ""