05/15/2024 15:19:45

Location Module

I. Overview

The Location module (Location Based Service, LBS) mainly provides games with functions related to the player's location. For example, the player can get the current location, get nearby friends, clear location settings, and query the country where the current IP is located. When using the LBS function, you should avoid frequently calling it in a short time.

Description: The Location module's "get IP-corresponding location info" interface supports domestic and overseas applications and requires no login. The remaining interfaces all only support domestic QQ and Wechat login.

II. Guide on how to access the module

Recommended process for accessing MSDK LBS:

• Register MSDK LBS callback
• Call MSDK LBS function

Access to MSDK LBS requires:

• MSDK initialization has been completed according to the Initialization module's instructions
• It is needed to log in MSDK before calling MSDK LBS interfaces

2.1 Configuration Instructions

1) Android configuration

• The Android platform's MSDK LBS positioning function depends on the support-v4 library. Remember to check whether the game project has imported support-v4 and support-v4's dependencies.
  MSDK uses support-v4-26.1.0 dependency version:

  • 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

• [Optional] Configure the MSDK environment. The field MSDK_LBS_GPS_TIMEOUT indicates that the GPS positioning timeout time is set (if not set, 4s by default).

• Android also needs to configure permissions and permission application window registration (in the AndroidManifest.xml file), as follows:

// Permission statement        
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />        
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />        

<application>        
    ......        
    // Dynamic permission application window registration        
    <activity android:name="com.tencent.gcloud.msdk.lbs.PermissionActivity"/>        

</application>

2) iOS configuration

• The iOS platform's dependency system library file: CoreLocation.framework

• Instructions for the user when applying for positioning permissions configuration in iOS: Add the configuration file info.pilst in Xcode projects

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

CurrentNeedLocation; instructions for the user when applying for positioning permissions

[warning] LBS Precautions

This configuration item must be added when the LBS function is used; otherwise, the use may be rejected and an exception in the use of the LBS function may be caused

2.2 Register the callback

1) Functional description

In order to receive the callback from the MSDK LBS module, the game needs to register the callback function at first.

2) Interface declaration

// Callback for getting the location information		
public static event OnMSDKRetEventHandler<MSDKLBSLocationRet> LBSLocationRetEvent;		
		
// Callback for getting the list of nearby people		
public static event OnMSDKRetEventHandler<MSDKLBSRelationRet> LBSRelationRetEvent;		
		
// Get the IP information list		
public static event OnMSDKRetEventHandler<MSDKLBSIPInfoRet> LBSIPInfoRetEvent;		
		
// Callback for clearing location information		
public static event OnMSDKRetEventHandler<MSDKBaseRet> LBSRetEvent;

class MSDKLBSObserver		
{		
public:		
    // Add a virtual destructor, otherwise UnrealEngine will report an error		
    virtual ~MSDKLBSObserver(){};		
		
    // Callback for getting the location information		
    virtual void OnLBSLocationRetNotify(const MSDKLBSLocationRet &locationRet) {};		
		
    // Callback for getting nearby people		
    virtual void OnLBSRelationRetNotify(const MSDKLBSRelationRet &relationRet) {};		
		
    // Callback for getting the IP information		
    virtual void OnLBSIPInfoRetNotify(const MSDKLBSIPInfoRet &ipInfoRet) {};		
		
    // Basic callback: Callback for clearing the location information		
    virtual void OnLBSBaseRetNotify(const MSDKBaseRet &baseRet) {};		
};

3) Demo code

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();		
		
    // Callback for getting the location information		
    virtual void OnLBSLocationRetNotify(const MSDKLBSLocationRet &locationRet);		
    // Callback for getting nearby people		
    virtual void OnLBSRelationRetNotify(const MSDKLBSRelationRet &relationRet);		
		
    // Callback for getting the IP information		
    virtual void OnLBSIPInfoRetNotify(const MSDKLBSIPInfoRet &ipInfoRet);		
    // Basic callback: Callback for clearing the location information		
    virtual void OnLBSBaseRetNotify(const MSDKBaseRet &baseRet);		
		
};		
#else		
		
class CLIENTUETEST_API MSDKLBSCallBacks : public MSDKBaseCallBacks		
{		
public:		
    MSDKLBSCallBacks();		
		
    ~MSDKLBSCallBacks();		
		
};		
		
#endif

4) Data structure

• Structure of the location-getting callback: Detailed description of MSDKLBSLocationRet
  
  It is inherited from MSDKBaseRet. The fields contained in it are as follows:

• Structure of the callback for getting the nearby people: Detailed description of MSDKLBSRelationRet
  
  It is inherited from MSDKBaseRet. The fields contained in it are as follows:

Wherein, the player list field, MSDKPersonInfo, is inherited from MSDKPersonInfo

• Structure of the callback for getting the Location information corresponding to IP: Detailed description of MSDKLBSIPInfoRet
  
  It is inherited from MSDKBaseRet. The fields contained in it are as follows:

• Structure of the callback for clearing the location information: MSDKBaseRet

2.3 Get the location

1) Functional description

When calling this interface, you can get the player's location information through base station positioning, WIFI positioning and GPS positioning (if any kind of positioning is successful). The interface returns the player's current latitude and longitude when it is called. It is recommended to add ACCESS_WIFI_STATE non-sensitive permissions to Android projects.

2) Call of the interface

// MSDK LBS' location-getting interface		
void GetLocation();

// MSDK LBS' location-getting interface		
void GetLocation();

3) Callback interface

// MSDK LBS' location-getting callback		
public void OnLBSGetLocationEvent(MSDKLBSLocationRet baseRet);

// Callback for getting the location information		
void OnLBSLocationRetNotify(const MSDKLBSLocationRet &locationRet);

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 Get nearby players

1) Functional description

Get a list of other positioned players near the player's location

2) Call of the interface

// MSDK LBS interface of getting nearby players		
void GetNearby();

// MSDK LBS interface of getting nearby players		
void GetNearby();

// MSDK LBS callback of getting nearby players		
public void OnLBSGetNearByEvent(MSDKLBSRelationRet lbsRelationRet);

// Callback for getting nearby people		
void OnLBSRelationRetNotify(const MSDKLBSRelationRet &relationRet);

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 Clear the location information

1) Functional description

In the function of getting the location and getting nearby friends, the player's information is set to the backend. Calling this interface can clear the backend's location setting for the player, so that the player does not appear in the nearby player list of other players.

2) Call of the interface

// MSDK LBS' location-clearing interface		
void ClearLocation();

// MSDK LBS' location-clearing interface		
void ClearLocation();

// MSDK LBS' location-clearing callback		
public void OnLBSClearLocationEvent(MSDKBaseRet baseRet);

void OnLBSBaseRetNotify(const MSDKBaseRet &baseRet);

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 Get the IP-corresponding location info

1) Functional description

The location information corresponding to the IP address of the current device network. Currently, MSDK can provide country, province and city information, of which province and city has been supported since MSDKV5.28. It is recommended that overseas regions only use country information.

2) Call of the interface

// MSDK LBS interface of getting the IP-corresponding location info			
void GetIPInfo();

// MSDK LBS interface of getting the IP-corresponding location info			
void GetIPInfo();

// MSDK LBS callback of getting the IP-corresponding location info			
public void OnLBSGetIpInfoEvent(MSDKLBSIPInfoRet lbsIpInfoRet);

// Callback for getting the IP information		
void OnLBSIPInfoRetNotify(const MSDKLBSIPInfoRet &ipInfoRet);

• Structure of the callback for getting the Location information corresponding to IP: Detailed description of MSDKLBSIPInfoRet
  
  It is inherited from MSDKBaseRet. The fields contained in it are as follows:

4) Demo code

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		
}