• UIKit
  • SDK
  • サーバー API
Chat/
SDK/
Android/
メッセージ/
SDK
  • Chat SDK のインストール
  • Chat SDK の初期化
  • ログインとログアウト
  • メッセージ
    • Overview
    • メッセージ送信
    • メッセージの受信
    • メッセージの検索
    • メッセージ転送
    • メッセージの変更
    • メッセージ挿入
    • メッセージ削除
    • 過去のメッセージをクリアします
    • メッセージの取り消し
    • オンラインメッセージの送信
    • メッセージの既読レシート
    • クエリーメッセージ
    • ヒント
    • ターゲットグループメッセージ
    • 通知しません
    • Key-Value の拡張
    • 反応
    • 翻訳
    • メッセージの先頭固定表示
  • セッション
    • Overview
    • セッションリスト
    • セッションの取得
    • 未読数
    • セッションの先頭固定表示
    • セッションの削除
    • 下書き
    • マーク
    • セッショングループ
  • グループ
    • Overview
    • グループ管理
    • プロファイル
    • メンバー管理
    • メンバープロファイル
    • プロパティ
    • カウンター
  • コミュニティとトピック
    • コミュニティ管理
    • 権限グループ
  • ユーザー
    • ユーザープロファイル
    • ユーザー状態
    • 友達の管理
    • 友達グループ
    • ブラックリスト
    • Follow
  • ローカル検索
    • メッセージ検索
    • 友達を検索
    • グループの検索
    • グループメンバーの検索
  • シグナリング
  • インターフェースリファレンスドキュメンテーション
    • Java
  • Guideline for Beginners
  • コンソールガイド
    • アプリケーションの作成とアップグレード
    • 基本設定
    • 機能設定
    • アカウント管理
    • グループ管理
    • コールバック設定
  • 製品紹介
    • メッセージ管理
      • シングルチャットメッセージ
      • メッセージの保存
      • オフラインプッシュ
      • グループメッセージ
      • メッセージフォーマット
    • アカウントシステム
      • ログイン認証
      • オンライン状態管理
    • グループ関連
      • グループシステム
      • グループ管理
    • ユーザープロファイルとリレーションシップチェーン
      • 資料管理
      • リレーションシップチェーン管理
  • 購入ガイド
    • 課金の概要
    • 価格
  • エラーコード
このページは現在英語版のみで提供されており、日本語版も近日中に提供される予定です。ご利用いただきありがとうございます。

Key-Value の拡張

Feature Description

Message extension allows you to configure keys and values for messages to implement more custom scenarios, such as polling, group notes, survey, etc.
For polling, create a custom message using the createCustomMessage (Android/iOS & Mac/Windows) API, where data stores the polling title and options. And store the user ID of the voter and selected option(s) in the key and value of the message extension, respectively. With the selected options of users, we can calculate the polling percentage real time.
For group notices, create a custom message for group notification using the createCustomMessage API, where data stores the title of the group notice, and then store the user ID and the corresponding info in the key and value of the message extension, respectively.
For survey, create a custom message using the createCustomMessage API, where data stores the title and options of the survey, and then store the user ID and the corresponding info in the key and value of the message extension, respectively.
Note:
To use this feature, you need to purchase the Premium edition.
This feature is available only in SDK enhanced edition v6.7 or later.
This feature needs to be enabled in the Console first, switch path: Applications > Your App > Chat > Configuration > Login and Message > Set message extension.
This feature is not available for audio/video groups (AVChatRoom).

Setting message extension

Call the setMessageExtensions (Android / iOS & Mac / Windows) API to set the message extension. If an extension already exists, modify its value info. Otherwise, add new ones.
The request parameters of the setMessageExtensions API are detailed as follows:
Attribute
Definition
Description
message
Message object
Three message conditions to meet:
Set supportMessageExtension (Android / iOS & macOS / Windows) to `YES` before message sending.
The message is sent successfully.
The message is not a message of a community/audio-video group.
extensions
Extensions
Modify the `value` info of an existing extension, or add new extensions.

Note
1. The key and value of an extension can contain up to 100 B and 1 KB, respectively. You can set up to 20 extensions each time and 300 extensions for a message.
2. If multiple users set or delete the key of the same extension simultaneously, only the first user can operate successfully, and other users will receive the error code 23001 and the latest extension info in the setting response packet, who can set it again if necessary.
3. We recommend setting unique keys of extensions by different users to avoid conflicts in most cases. For example, the userID can be set as the key of the extension in polling, group notices and survey.
Sample code:
Android
iOS and macOS
Windows
List<V2TIMMessageExtension> extensionList = new ArrayList<>();
V2TIMMessageExtension extension1 = new V2TIMMessageExtension();
extension1.setExtensionKey("key1");
extension1.setExtensionValue("value1");
extensionList.add(extension1);
V2TIMMessageExtension extension2 = new V2TIMMessageExtension();
extension2.setExtensionKey("key2");
extension2.setExtensionValue("value2");
extensionList.add(extension2);
V2TIMManager.getMessageManager().setMessageExtensions(lastMsg, extensionList, new V2TIMValueCallback<List<V2TIMMessageExtensionResult>>() {
@Override
public void onSuccess(List<V2TIMMessageExtensionResult> v2TIMMessageExtensionResults) {
// Set message extensions successfully
}

@Override
public void onError(int code, String desc) {
// Failed to set message extensions
}
});

NSMutableArray *extensionList = [NSMutableArray array];
V2TIMMessageExtension *extension1 = [[V2TIMMessageExtension alloc] init];
extension1.extensionKey = @"key1";
extension1.extensionValue = @"value1";
[extensionList addObject:extension1];
V2TIMMessageExtension *extension2 = [[V2TIMMessageExtension alloc] init];
extension2.extensionKey = @"key2";
extension2.extensionValue = @"value2";
[extensionList addObject:extension2];
[[V2TIMManager sharedInstance] setMessageExtensions:message extensions:extensionList succ:^(NSArray<V2TIMMessageExtensionResult *> *extensionResultList) {
// Set message extensions successfully
} fail:^(int code, NSString *desc) {
// Failed to set message extensions
}];
class ValueCallback final : public V2TIMValueCallback<T> {
public:
using SuccessCallback = std::function<void(const T &)>;
using ErrorCallback = std::function<void(int, const V2TIMString &)>;

ValueCallback() = default;
~ValueCallback() override = default;

void SetCallback(SuccessCallback success_callback, ErrorCallback error_callback) {
success_callback_ = std::move(success_callback);
error_callback_ = std::move(error_callback);
}

void OnSuccess(const T &value) override {
if (success_callback_) {
success_callback_(value);
}
}
void OnError(int error_code, const V2TIMString &error_message) override {
if (error_callback_) {
error_callback_(error_code, error_message);
}
}

private:
SuccessCallback success_callback_;
ErrorCallback error_callback_;
};

V2TIMMessageExtensionVector extensionList;
V2TIMMessageExtension extension1;
extension1.extensionKey = "key1";
extension1.extensionValue = "value1";
extensionList.PushBack(extension1);
V2TIMMessageExtension extension2;
extension2.extensionKey = "key2";
extension2.extensionValue = "value2";
extensionList.PushBack(extension2);

auto *callback = new ValueCallback<V2TIMMessageExtensionResultVector>{};
callback->SetCallback(
[=](const V2TIMMessageExtensionResultVector &extensionResultList) {
// Set message extensions successfully
delete callback;
},
[=](int error_code, const V2TIMString &error_message) {
// Failed to set message extensions
delete callback;
});

V2TIMManager::GetInstance()->GetMessageManager()->SetMessageExtensions(message, extensionList, callback);

Getting message extensions

Get the message extension list by calling getMessageExtensions (Android/iOS & Mac/Windows).
Note
If the network is unavailable, the SDK will return the message extension list cached locally.
Sample code:
Android
iOS and macOS
Windows
V2TIMManager.getMessageManager().getMessageExtensions(lastMsg, new V2TIMValueCallback<List<V2TIMMessageExtension>>() {
@Override
public void onSuccess(List<V2TIMMessageExtension> extensions) {
// Got message extensions successfully
}

@Override
public void onError(int code, String desc) {
// Failed to get message extensions
}
});
[[V2TIMManager sharedInstance] getMessageExtensions:message succ:^(NSArray<V2TIMMessageExtension *> *extensionList) {
// Got message extensions successfully
} fail:^(int code, NSString *desc) {
// Failed to get message extensions
}];
class ValueCallback final : public V2TIMValueCallback<T> {
public:
using SuccessCallback = std::function<void(const T &)>;
using ErrorCallback = std::function<void(int, const V2TIMString &)>;

ValueCallback() = default;
~ValueCallback() override = default;

void SetCallback(SuccessCallback success_callback, ErrorCallback error_callback) {
success_callback_ = std::move(success_callback);
error_callback_ = std::move(error_callback);
}

void OnSuccess(const T &value) override {
if (success_callback_) {
success_callback_(value);
}
}
void OnError(int error_code, const V2TIMString &error_message) override {
if (error_callback_) {
error_callback_(error_code, error_message);
}
}

private:
SuccessCallback success_callback_;
ErrorCallback error_callback_;
};

auto *callback = new ValueCallback<V2TIMMessageExtensionVector>{};
callback->SetCallback(
[=](const V2TIMMessageExtensionVector &extensionList) {
// Got message extensions successfully
delete callback;
},
[=](int error_code, const V2TIMString &error_message) {
// Failed to get message extensions
delete callback;
});

V2TIMManager::GetInstance()->GetMessageManager()->GetMessageExtensions(message, callback);

Deleting message extensions

Call deleteMessageExtensions (Android/iOS & Mac/Windows) to delete message extensions. If the value of the keys field is set to null/nil, all message extensions will be cleared.
Sample code:
Android
iOS and macOS
Windows
List<String> keyList = new ArrayList<>();
keyList.add("key1");
keyList.add("key2");
V2TIMManager.getMessageManager().deleteMessageExtensions(lastMsg, keyList, new V2TIMValueCallback<List<V2TIMMessageExtensionResult>>() {
@Override
public void onSuccess(List<V2TIMMessageExtensionResult> v2TIMMessageExtensionResults) {
// Deleted message extensions successfully
}

@Override
public void onError(int code, String desc) {
// Failed to delete message extensions
}
});
[[V2TIMManager sharedInstance] deleteMessageExtensions:message keys:@[@"key1",@"key2"] succ:^(NSArray<V2TIMMessageExtensionResult *> *extensionResultList){
// Deleted message extensions successfully
} fail:^(int code, NSString *desc) {
// Failed to delete message extensions
}];
class ValueCallback final : public V2TIMValueCallback<T> {
public:
using SuccessCallback = std::function<void(const T &)>;
using ErrorCallback = std::function<void(int, const V2TIMString &)>;

ValueCallback() = default;
~ValueCallback() override = default;

void SetCallback(SuccessCallback success_callback, ErrorCallback error_callback) {
success_callback_ = std::move(success_callback);
error_callback_ = std::move(error_callback);
}

void OnSuccess(const T &value) override {
if (success_callback_) {
success_callback_(value);
}
}
void OnError(int error_code, const V2TIMString &error_message) override {
if (error_callback_) {
error_callback_(error_code, error_message);
}
}

private:
SuccessCallback success_callback_;
ErrorCallback error_callback_;
};

V2TIMStringVector keys;
keys.PushBack("key1");
keys.PushBack("key2");

auto *callback = new ValueCallback<V2TIMMessageExtensionResultVector>{};
callback->SetCallback(
[=](const V2TIMMessageExtensionResultVector &extensionResultList) {
// Deleted message extensions successfully
delete callback;
},
[=](int error_code, const V2TIMString &error_message) {
// Failed to delete message extensions
delete callback;
});

V2TIMManager::GetInstance()->GetMessageManager()->DeleteMessageExtensions(message, keys, callback);

Updating message extensions

If you have added an event listener for advanced messages by calling addAdvancedMsgListener, you will receive the onRecvMessageExtensionsChanged (Android/iOS & Mac/Windows) callback when message extensions are added or updated, and the onRecvMessageExtensionsDeleted (Android/iOS & Mac/Windows) callback when message extensions are deleted.
Sample code:
Android
iOS and macOS
Windows
V2TIMManager.getMessageManager().addAdvancedMsgListener(new V2TIMAdvancedMsgListener() {
@Override
public void onRecvMessageExtensionsChanged(String msgID, List<V2TIMMessageExtension> extensions) {
// Received a notification of message extension change
}

@Override
public void onRecvMessageExtensionsDeleted(String msgID, List<String> extensionKeys) {
// Received a notification of message extension deletion
}
});
[[V2TIMManager sharedInstance] addAdvancedMsgListener:self];
- (void)onRecvMessageExtensionsChanged:(NSString *)msgID extensions:(NSArray<V2TIMMessageExtension *> *)extensions {
// Received a notification of message extension change
}
- (void)onRecvMessageExtensionsDeleted:(NSString *)msgID extensionKeys:(NSArray<NSString *> *)extensionKeys {
// Received a notification of message extension deletion
}
class AdvancedMsgListener final : public V2TIMAdvancedMsgListener {
public:
void OnRecvMessageExtensionsChanged(const V2TIMString &msgID,
const V2TIMMessageExtensionVector &extensions) override {
// Received a notification of message extension change
}

void OnRecvMessageExtensionsDeleted(const V2TIMString &msgID,
const V2TIMStringVector &extensionKeys) override {
// Received a notification of message extension deletion
}
// Other members …
};

// Add an event listener for advanced messages. Keep `advancedMsgListener` valid before it is removed to ensure event callbacks are received.
AdvancedMsgListener advancedMsgListener;
V2TIMManager::GetInstance()->GetMessageManager()->AddAdvancedMsgListener(&advancedMsgListener);