iOS Conversation: Metadata

Custom metadata can be sent to Khoros Response, allowing for important contextual information to be relayed to the agent and/or admin that conveys information such as:

Operating system
Membership status
Shopping cart contents
App version

We can set and manage metadata going along with messages. There is a set of default metadata that is added to each outgoing message before sending. Additionally, we have an option to set custom metadata.

The default metadata that is set contains the following data:

metadata[@"vendor"] = @"brandMessenger";
metadata[@"os"] = @"iOS";
metadata[@"sdkVersion"] = sdkVersion; // eg: 0.3.0
metadata[@"appId"] = appId; // eg: com.app.brandmessenger
metadata[@"appVersion"] = majorAppVersion; // eg: 1.0
metadata[@"client.appName"] = appName; // eg: Khoros App
metadata[@"client.osVersion"] = osVersion; // eg: Version 15.3 (Build 19D49)
metadata[@"client.devicePlatform"] = deviceName; // eg: Test iPhone 12 mini
metadata[@"client.buildNumber"] = buildNumber; // eg: 10
metadata[@"client.carrier"] = [carrier carrierName]; // 
metadata[@"client.platform"] = @"ios";

As you can see, each object must be a flat key/value pair of strings. If there are any other data types other than string, they must be converted to string and sent as key-value pair. Nested objects are not supported at this time.

For adding custom metadata KBMConversationDelegate can be implemented to intercept each message before sending and add new metadata. To do that:

Implement KBMConversationDelegate in your class for modifying messages.
Add the following lines to the above class.

class YourClass: KBMConversationDelegate {
   BrandMessengerManager.setConversationDelegate(self)

   ...
   func modifyMessage(beforeSend message: KBMMessage) -> KBMMessage {
    // message.metadata contains default metadata that can be overwritten/removed here
    message.metadata?.setValue("customVal1", forKey: "customKey1")
    return message
   }
}

@interface YourClass<KBMConversationDelegate>
// ...
@end

@implementation YourClass
[BrandMessengerManager setConversationDelegate:self];

...

-(KBMMessage *)modifyMessageBeforeSend: (KBMMessage *) message {
   NSMutableDictionary *metadata = [[NSMutableDictionary alloc]initWithDictionary:message.metadata];
   metadata[@"appName"] = appName;
   [message setMetadata:metadata];
   return message;
}

@end

Metadata can also be added in a global way (in contrast to per-message method above).

let metadata = NSMutableDictionary();
BrandMessengerSettings.setMessageMetadata(metadata);

NSMutableDictionary* metadata = [@{} mutableCopy];
[BrandMessengerSettings setMessageMetadata:metadata];

Lastly, in the Agent's Admin page, in Developer -> Metadata Visibility, add the Brand Messenger network. This will show the default fields like client.platform. Add the fields from the dictionary like appName, and they should be visible under each message in the conversation under the metadata section. Displayed metadata names are configurable from the admin tab of the Care web instance.