Skip to main content

Location Message

IMKit provides location messaging capabilities based on the AMap SDK, enabling in-app location sharing, thumbnail previews, and map viewing.

  • By default, the SDK sends messages containing a LocationMessage object (type identifier: RC:LBSMsg).
  • Real-time location sharing is also implemented via messages. The SDK uses message types RC:RL, RC:RLStart, RC:RLJoin, and RC:RLQuit for this feature.
tip

The default chat UI in IMKit does not enable location features. To use location functionality, integrate the IMKit location plugin locationKit and configure your own AMap SDK account.

message-location(width=250) message-location-share(width=250)

Limitations​

  • The IMKit location plugin currently only supports the AMap SDK. If you need to use other map services, you can create a custom plugin to construct and send location messages. For details on adding custom plugins, see Input Area.

Usage​

IMKit has supported the locationKit plugin since version 5.2.3. If upgrading from an IMKit version below 5.2.3, refer to Upgrading the Legacy Location Plugin.

Apply for an AMap API Key​

When using the locationKit plugin to send location messages, IMKit calls AMap's static map creation interface. Therefore, you need to apply for a Web Service API Key (Key) from AMap. Create a Web Service on the AMap platform to generate an API Key.

Integrate the Location Plugin​

  1. Integrate the location plugin library:

    Local Library Files: Download AMap location-related library files from the official website. Copy the locationKit_<ver>.aar file from the LocationLib folder in the downloaded package to your project's libs directory, then add the dependency in your app's build.gradle.

    location

        dependencies {
            implementation fileTree(include: ['*.jar', '*.aar'], dir: 'libs')
            ...
        }

    Maven:

    // The plugin version must match the main SDK version.
    implementation 'cn.rongcloud.sdk:locationKit:x.y.z'
    tip

    The latest version numbers for each SDK may differ and could be x.y.z.h. Check the RC Official SDK Download Page or RC's Maven Repository for details.

  2. Open your app's AndroidManifest.xml file and add the AMap API Key to the meta-data tag under the application section.

    <meta-data
        android:name="com.amap.api.v2.apikey"
        android:value="Your AMap API Key" />

  3. Add AMap privacy compliance code.

    Integrating locationKit requires compliance with AMap's Privacy Compliance Interface Guidelines. Failure to do so may cause app crashes.

    Add AMap's privacy policy to your app's privacy agreement. After obtaining user consent, call the following code before the first invocation of any map plugin functionality:

    // Indicates user consent to location privacy terms
    AMapLocationClient.updatePrivacyShow(this, true, true);
    AMapLocationClient.updatePrivacyAgree(this, true);

    // Indicates user consent to map privacy terms
    MapsInitializer.updatePrivacyShow(this, true, true);
    MapsInitializer.updatePrivacyAgree(this, true);

    // Indicates user consent to search privacy terms
    ServiceSettings.updatePrivacyShow(this, true, true);
    ServiceSettings.updatePrivacyAgree(this, true);

    After completing these steps, the AMap 3D map integration is complete, and the location plugin will automatically appear in the extension panel.

  4. (Optional) Configure code obfuscation. See Obfuscation.

Send Location Messages​

After integrating the location plugin, the location message option will automatically appear in the extension panel. Users can click the + button on the right side of the input bar to expand the panel and tap the location icon to send a location message.

extension(width=250)

By default, the integrated location plugin provides the following capabilities:

  • In one-to-one chats, clicking the location plugin displays options for Send Location and Real-Time Location Sharing. Users can choose to send a location or initiate real-time sharing. You can also disable real-time sharing for one-to-one chats.
  • Group chats do not enable Real-Time Location Sharing by default; only location sending is available. You can manually enable this option for group chats.

Use Real-Time Location Sharing​

You can customize the extension panel configuration to modify real-time location sharing settings.

  1. Create a custom extension panel configuration class MyExtensionConfig that extends DefaultExtensionConfig and override the getPluginModules() method.

    public class MyExtensionConfig extends DefaultExtensionConfig {
        @Override
        public List<IPluginModule> getPluginModules(Conversation.ConversationType conversationType, String targetId) {
            List<IPluginModule> pluginModules = super.getPluginModules(conversationType,targetId);
            ListIterator<IPluginModule> iterator = pluginModules.listIterator();

            while (iterator.hasNext()) {
                IPluginModule integer = iterator.next();
                // Remove DefaultLocationPlugin if real-time sharing is unsupported
                if (integer instanceof DefaultLocationPlugin) {
                    iterator.remove();
                }
            }

            // Add CombineLocationPlugin for real-time sharing support
            pluginModules.add(new CombineLocationPlugin());
            return pluginModules;
        }
    }

  2. After initializing the SDK, call the following method to set the custom input configuration. The SDK will display the extension panel based on this configuration.

    RongExtensionManager.getInstance().setExtensionConfig(new MyExtensionConfig());

You can also modify the default configuration. Create an rc_configuration.xml file under res/values and add the following configuration to specify conversation types that support real-time location sharing. To disable the feature, remove the corresponding item.

<!--Conversation types supporting real-time location sharing-->
<string-array name="rc_realtime_support_conversation_types" translatable="false">
    <item>private</item>
    <item>group</item>
</string-array>

Upgrading the Legacy Location Plugin​

tip

When upgrading from pre-5.2.3 IMKit versions to 5.2.3, the legacy location plugin becomes obsolete.

Starting with IMKit 5.2.3, the default AMap developer account is no longer provided. To use location features, configure your own AMap SDK account.

If integrating the new plugin, ensure the following legacy JAR files are removed to avoid compilation errors:

tip
  • Android_Map3D_SDK_v6.9.3.jar
  • AMap_Search_v6.9.3.jar
  • MapApiLocationMini.jar
  • libAMapSDK_MAP_v6_9_3.so
  • libJni_wgs2gcj.so

Customization​

Adjust Location Thumbnail Compression Ratio​

When sending location messages, the SDK automatically generates a preview map image, uploads it to the file server (default: Qiniu Cloud Storage), and includes the remote URL in the message body. The SDK compresses images to a maximum width of 408 pixels and height of 240 pixels.

To adjust compression settings, create an rc_configuration.xml file under res/values and modify the following configurations:

<!--Location message thumbnail compression quality-->
<integer name="rc_location_thumb_quality">70</integer>
<!--Location message thumbnail width-->
<integer name="rc_location_thumb_width">408</integer>
<!--Location message thumbnail height-->
<integer name="rc_location_thumb_height">240</integer>

Customize Location Message UI​

Location messages are displayed in the message list using the LocationMessageItemProvider and RealTimeLocationMessageItemProvider templates.

To modify built-in message styles, implement your own message display template class and provide it to the SDK. All message templates inherit from BaseMessageItemProvider<CustomMessage>. For details, see Customizing Message Display Styles.

Last updated on