跳到主要内容

位置消息

IMKit 基于高德地图 SDK 提供了位置消息，实现了应用内位置共享、位置缩略图与地图预览功能。

  • SDK 默认发送的消息包含位置消息内容对象 LocationMessage（类型标识：RC:LBSMsg）。
  • 实时位置共享也是基于消息实现的。SDK 默认使用类型标识为 RC:RL、RC:RLStart、RC:RLJoin、RC:RLQuit 的消息。
提示

IMKit 默认会话页面未启用位置功能。如需要使用位置功能，可集成 IMKit 位置插件并配置您自己的高德地图 SDK 帐号。

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

局限​

  • IMKit 的位置插件目前存在仅支持高德地图 SDK。如需使用其他地图服务，您可以自定义插件，自行构造位置消息并发送。添加自定义插件的方法详见输入区域。

用法​

IMKit 从 5.2.3 及之后开始支持 locationKit 插件。如果从低于 5.2.3 的 IMKit 版本升级，请参见下文升级旧版位置插件。

重要

IMKit 5.2.3 - 5.6.6 版本存在已知问题，无法正常发送位置消息。建议您尽快升级到 5.6.7 及之后版本。如果暂时无法升级，可参考知识库文档中的修复方案，详见 解决内置高德地图 ApiKey 失效，导致无法正常发送位置消息的问题。

自行申请高德地图 API Key​

IMKit 使用 locationKit 插件发送位置消息时，需要调用高德地图的创建静态图接口，因此您需要申请高德地图申请 Web 服务 API 密钥（Key）。在高德平台创建一个 Web 服务后，可生成 API Key。

集成位置插件​

  1. 集成位置插件库：

    本地库文件：从官网下载高德位置相关的库文件。将下载包里 LocationLib 文件夹下的 locationKit_<ver>.aar 文件拷贝到项目的 libs 目录下，并在应用的 build.gradle 中添加依赖。

    location

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

    Maven：

    // 插件版本需要与主 SDK 版本保持一致。
    implementation 'cn.rongcloud.sdk:locationKit:x.y.z'
    提示

    各个 SDK 的最新版本号可能不相同，还可能是 x.y.z.h，可前往 融云官网 SDK 下载页面 或 融云的 Maven 代码库 查询。

  2. 打开应用的 AndroidManifest.xml 文件，把从高德官网获取的 ApiKey 添加到 application 标签的 meta-data 里。

    <meta-data
        android:name="com.amap.api.v2.apikey"
        android:value="高德地图的 ApiKey" />

  3. 添加高德隐私协议代码。

    集成 locationKit 需要遵守高德地图 隐私合规接口说明，否则会导致应用崩溃。

    请在您当前应用的隐私协议中添加高德平台隐私政策，在获取用户同意之后，并在第一次调用地图插件功能之前调用以下代码：

    // 表示用户同意定位功能隐私协议
    AMapLocationClient.updatePrivacyShow(this, true, true);
    AMapLocationClient.updatePrivacyAgree(this, true);

    // 表示用户同意地图功能隐私协议
    MapsInitializer.updatePrivacyShow(this, true, true);
    MapsInitializer.updatePrivacyAgree(this, true);

    // 表示用户同意搜索功能隐私协议
    ServiceSettings.updatePrivacyShow(this, true, true);
    ServiceSettings.updatePrivacyAgree(this, true);

    通过以上步骤，即完成了高德 3D 地图的集成，在扩展面板里会自动生成位置插件。

  4. （可选）配置代码混淆。详见混淆。

发送位置消息​

位置插件集成完毕后，在扩展面板里会自动生成位置消息入口。用户点击输入栏右侧 + 号按钮可展开扩展面板，点击位置图标，即可发送位置消息。

extension(width=250)

集成位置插件后，默认能力如下：

  • 单聊会话中点击位置插件时，会有 发送位置和实时位置共享两个功能选项。用户可以选择发送实时位置或发起位置共享。您也可以为单聊会话关闭实时位置共享。
  • 群聊会话中默认没有开启 实时位置共享，仅可以发送位置。您可以自行为群聊会话启用该选项。

使用实时位置共享​

您可以创建自定义的扩展面板配置，修改是否需要启用实时位置共享。

  1. 创建自定义的扩展面板配置类 MyExtensionConfig，继承自 DefaultExtensionConfig，重写其中的 getPluginModules() 方法。

    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();
                // 删除不支持实时位置共享的  DefaultLocationPlugin
                if (integer instanceof DefaultLocationPlugin) {
                    iterator.remove();
                }
            }

            // 添加支持实时位置共享的 CombineLocationPlugin 扩展项
            pluginModules.add(new CombineLocationPlugin());
            return pluginModules;
        }
    }

  2. SDK 初始化之后，调用以下方法设置自定义的输入配置，SDK 会根据此配置展示扩展面板。

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

您也可以通过修改默认配置。在 res/values 下创建 IMLib 的配置文件 rc_configuration.xml 文件中，添加并调整以下配置，配置需要支持实时位置共享的会话类型。如果需要关闭位置共享功能，可以移除相应的 item。

<!--实时位置共享会话类型-->
<string-array name="rc_realtime_support_conversation_types" translatable="false">
    <item>private</item>
    <item>group</item>
</string-array>

升级旧版位置插件​

提示

IMKit 5.2.3 之前版本升级到 5.2.3 时，旧版位置插件即失效。

从 IMKit 5.2.3 版本开始，不再提供默认的高德地图开发账号。如开发者需要使用位置功能，可配置自己的高德地图 SDK 帐号集成使用。

如集成新版插件，请务必将原来集成的以下 Jar 包删除，否则会导致编译失败。

提示
  • Android_Map3D_SDK_v6.9.3.jar
  • AMap_Search_v6.9.3.jar
  • MapApiLocationMini.jar
  • libAMapSDK_MAP_v6_9_3.so
  • libJni_wgs2gcj.so

定制化​

调整位置缩略图压缩比例​

从客户端发送位置消息时，SDK 会自动生成预览地图图片，自动上传到文件服务器（默认上传到七牛云存储），并将云存储服务返回的图片的远程地址放入消息体对应字段后进行发送。SDK 会以宽度不超过 408 像素、高度不超过 240 进行压缩。

您可以在应用程序目录下创建 res/values/rc_configuration 文件，修改以下配置调整预览地图压缩比例与图片尺寸：

// 位置消息缩略图压缩比例
<integer name="rc_location_thumb_quality">70</integer>
// 位置消息缩略图压缩宽度
<integer name="rc_location_thumb_width">408</integer>
// 位置消息缩略图压缩高度
<integer name="rc_location_thumb_height">240</integer>

自定义位置消息的 UI​

位置消息使用 LocationMessageItemProvider 模板和 RealTimeLocationMessageItemProvider 模板展示在消息列表中。

如果需要调整内置消息样式，建议自行实现消息展示模板类，并将该自定义模板提供给 SDK。所有消息模板都继承自 BaseMessageItemProvider<CustomMessage>，自定义消息展示模板也需要继承 BaseMessageItemProvider<CustomMessage>。详见修改消息的展示样式。