Home
/
Chat
/
iOS

User & channel metadata

With metadata and metacounter which consist of key-value items, you can store additional information to users and channels. This page explains how to manage user metadata, channel metadata, and channel metacounter.

Note : User metadata, channel metadata, and channel metacounter can each have up to 5 key-value items. The key’s length must be no larger than 128 characters. For user metadata and channel metadata, the value must be a NSString and its length must be no larger than 190 characters. For channel metacounter, the value must be a NSNumber.


User metadata

You can store additional information to users such as phone number, email or a long description of a user with user metadata, which can be fetched or rendered into the UI. A user metadata is a NSDictionary<NSString *, NSString *> and it can be stored into a SBDUser object.

Create user metadata

To store a user metadata into a SBDUser object, add key-value items after creating a NSDictionary<NSString *, NSString *>, and pass it as an argument to a parameter when calling the createMetaData:completionHandler: method. You can put multiple key-value items in the dictionary.

Objective-C
Swift
Light Color Skin
Copy
SBDUser *user = [SBDMain getCurrentUser];

NSDictionary *data = @{@"key1": @"value1",
    @"key2": @"vaule2"};

[user createMetaData:data completionHandler:^(NSDictionary * _Nullable metaData, SBDError * _Nullable error) {
    if (error != nil) {
        // Handle error.
    }

    ...
}];
Light Color Skin
Copy
let user = SBDMain.getCurrentUser()!

let data = [
    "key1": "value1",
    "key2": "value2"
]

user.createMetaData(data, completionHandler: { (metaData, error) in
    guard error == nil else {
        // Handle error.
    }

    ...
})

Update user metadata

The procedure to update a user metadata is the same as creating a user metadata. Values of existing keys will be updated and values of new keys will be added.

Objective-C
Swift
Light Color Skin
Copy
SBDUser *user = [SBDMain getCurrentUser];

NSDictionary *data = @{@"key1": @"valueToUpdate1",
    @"key2": @"valueToUpdate2"};

[user updateMetaData:data completionHandler:^(NSDictionary * _Nullable metaData, SBDError * _Nullable error) {
    if (error != nil) {
        // Handle error.
    }

    ...
}];
Light Color Skin
Copy
let user = SBDMain.getCurrentUser()!

let data = [
    "key1": "valueToUpdate1",
    "key2": "valueToUpdate2"
]

user.updateMetaData(data, completionHandler: { (metaData, error) in
    guard error == nil else {
        // Handle error.
    }

    ...
})

Retrieve user metadata

You can retrieve user metadata by reading the metadata property of a SBDUser object.

Objective-C
Swift
Light Color Skin
Copy
SBDUser *user = [SBDMain getCurrentUser];
NSDictionary *metaData = user.metaData;
Light Color Skin
Copy
let user = SBDMain.getCurrentUser()!
let metaData = user.metaData

Delete user metadata

You can delete a user metadata as below.

Objective-C
Swift
Light Color Skin
Copy
SBDUser *user = [SBDMain getCurrentUser];

[user deleteMetaDataWithKey:@"key1" completionHandler:^(SBDError * _Nullable error) {
    if (error != nil) {
        // Handle error.
    }

    ...
}];
Light Color Skin
Copy
let user = SBDMain.getCurrentUser()!

user.deleteMetaData(withKey: "key1", completionHandler: { (error) in
    guard error == nil else {
        // Handle error.
    }

    ...
})

Channel metadata

You can store additional information to channels such as background color or a long description of a channel with channel metadata, which can be fetched or rendered into the UI. A channel metadata is a NSDictionary<NSString *, NSString *> and it can be stored into a SBDOpenChannel or a SBDGroupChannel object.

Create channel metadata

To store a channel metadata into a channel, add key-value items after creating a NSDictionary<NSString *, NSString *>, and pass it as an argument to a parameter when calling the createMetaData:completionHandler: method. You can put multiple key-value items in the dictionary.

Objective-C
Swift
Light Color Skin
Copy
[SBDOpenChannel getChannelWithUrl:CHANNEL_URL completionHandler:^(SBDOpenChannel * _Nonnull channel, SBDError * _Nullable error) {
    NSDictionary *newMetaData = @{@"key1": @"value1",
                @"key2": @"value2"};

    [channel createMetaData:newMetaData completionHandler:^(NSDictionary * _Nullable metaData, SBDError * _Nullable error) {
        if (error != nil) {
            // Handle error.
        }

        ...
    }];
}];
Light Color Skin
Copy
SBDOpenChannel.getWithUrl(CHANNEL_URL, completionHandler: { (channel, error) in
    let newMetaData: NSDictionary = [
        "key1": "value1",
        "key2": "value2"
    ]

    channel?.createMetaData(newMetaData, completionHandler: { (metaData, error) in
        guard error == nil else {
            // Handle error.
            }

        ...
    })
})

Update channel metadata

The procedure to update a channel metadata is the same as creating a channel metadata. Values of existing keys will be updated and values of new keys will be added.

Objective-C
Swift
Light Color Skin
Copy
[SBDOpenChannel getChannelWithUrl:CHANNEL_URL completionHandler:^(SBDOpenChannel * _Nonnull channel, SBDError * _Nullable error) {
    NSDictionary *metaDataToUpdate = @{@"key1": @"valueToUpdate1",      // Update an existing item with a new value.
                @"key2": @"valueToUpdate2",         // Update an existing item with a new value
                @"key3": @"valueToAdd3"};           // Add a new key-value item.

    [channel updateMetaData:metaDataToUpdate completionHandler:^(NSDictionary * _Nullable metaData, SBDError * _Nullable error) {
        if (error != nil) {
            // Handle error.
        }

        ...
    }];
}];
Light Color Skin
Copy
SBDOpenChannel.getWithUrl(CHANNEL_URL, completionHandler: { (channel, error) in
    let metaDataToUpdate: NSDictionary = [
        "key1": "valueToUpdate1",   // Update an existing item with a new value.
        "key2": "valueToUpdate2",   // Update an existing item with a new value.
        "key3": "valueToAdd3"       // Add a new key-value item.
    ]

    channel?.updateMetaData(metaDataUpUpdate, completionHandler: { (metaData, error) in
        guard error == nil else {
            // Handle error.
            }

        ...
    })
})

Retrieve channel metadata

You can retrieve channel metadata by creating a NSArray of keys to retrieve and passing it as an argument to a parameter in the getMetaDataWithKeys:completionHandler: method. A NSDictionary<NSString *,NSObject *> will return through the completionHandler with corresponding key-value items.

Objective-C
Swift
Light Color Skin
Copy
[SBDOpenChannel getChannelWithUrl:CHANNEL_URL completionHandler:^(SBDOpenChannel * _Nonnull channel, SBDError * _Nullable error) {
    NSArray *keys = @[@"key1", @"key2"];

    [channel getMetaDataWithKeys:keys completionHandler:^(NSDictionary * _Nullable metaData, SBDError * _Nullable error) {
        if (error != nil) {
            // Handle error.
        }

        ...
    }];
}];
Light Color Skin
Copy
SBDOpenChannel.getWithUrl(CHANNEL_URL, completionHandler: { (channel, error) in
    let keys : NSArray = ["key1", "key2"]

    channel?.getMetaData(withKeys: keys, completionHandler: { (metaData, error) in
        guard error == nil else {
            // Handle error.
        }

        ...
    })
})

Retrieve cached channel metadata

When Sendbird Chat SDK detects any of the create, read, update, and delete operations on the channel metadata, the SDK caches the metadata. The cached metadata is also updated whenever a channel list is fetched.

You can retrieve the metadata through the getCachedMetaData() method without having to query the server.

Objective-C
Swift
Light Color Skin
Copy
NSDictionary *cachedMetaData = [channel getCachedMetaData];
NSString *value = cachedMetaData[key]; // The key should be string.
Light Color Skin
Copy
let cachedMetaData = channel.getCachedMetaData()
let value = cachedMetaData[key] // The key should be string.

Delete channel metadata

You can delete a channel metadata as below.

Objective-C
Swift
Light Color Skin
Copy
[channel deleteMetaDataWithKey:@"key1" completionHandler:^(SBDError * _Nullable error) {
    if (error != nil) {
        // Handle error.
    }

    ...
}];
Light Color Skin
Copy
channel.deleteMetaData(withKey: "key1", completionHandler: { (error) in
    guard error == nil else {
        // Handle error.
    }

    ...
})

Channel metacounter

You can store additional information to channels such as the tracking number of likes with channel metacounter, which can be fetched or rendered into the UI. A channel metacounter is a NSDictionary<NSString *, NSNumber *> and it can be stored into a SBDOpenChannel or a SBDGroupChannel object.

Note : A channel metacounter is primarily used to track and update discrete indicators in a channel. Use channel metacounter instead of channel metadata when you need an integer with atomic increasing and decreasing operations.

Create

To store a metacounter into a channel, add key-value items after creating a NSDictionary<NSString *, NSNumber *>, and pass it as an argument to a parameter when calling the createMetaCounters:completionHandler: method. You can put multiple key-value items in the dictionary.

Objective-C
Swift
Light Color Skin
Copy
[SBDOpenChannel getChannelWithUrl:CHANNEL_URL completionHandler:^(SBDOpenChannel * _Nonnull channel, SBDError * _Nullable error) {
    NSDictionary *newMetaCounters = @{@"key1": @(1),
                @"key2": @(2)};

    [channel createMetaCounters:newMetaCounters completionHandler:^(NSDictionary * _Nullable metaCounters, SBDError * _Nullable error) {
        if (error != nil) {
            // Handle error.
        }

        ...
    }];
}];
Light Color Skin
Copy
SBDOpenChannel.getWithUrl(CHANNEL_URL, completionHandler: { (channel, error) in
    let newMetaCounters: NSDictionary = [
        "key1": 1,
        "key2": 2
    ]

    channel?.createMetaCounters(newMetaCounters, completionHandler: { (metaCounters, error) in
        guard error == nil else {
            // Handle error.
        }

        ...
    })
})

Update

The procedure to update a channel metacounter is the same as creating a channel metacounter. Values of existing keys will be updated and values of new keys will be added.

Objective-C
Swift
Light Color Skin
Copy
[SBDOpenChannel getChannelWithUrl:CHANNEL_URL completionHandler:^(SBDOpenChannel * _Nonnull channel, SBDError * _Nullable error) {
    NSDictionary *metaCountersToUpdate = @{@"key1": @(3),   // Update 1 to 3.
                @"key2": @(4),              // Update 2 to 4.
                @"key3": @(0)};             // Add a new key-value item.

    [channel updateMetaCounters:metaCountersToUpdate completionHandler:^(NSDictionary * _Nullable metaCounters, SBDError * _Nullable error) {
        if (error != nil) {
            // Handle error.
        }

        ...
    }];
}];
Light Color Skin
Copy
SBDOpenChannel.getWithUrl(CHANNEL_URL, completionHandler: { (channel, error) in
    let metaCountersToUpdate: NSDictionary = [
        "key1": 3,  // Update 1 to 3.
        "key2": 4,  // Update 2 to 4.
        "key3": 0   // Add a new key-value item.
    ]

    channel?.updateMetaCounters(metaCountersToUpdate, completionHandler: { (metaCounters, error) in
        guard error == nil else {
            // Handle error.
        }

        ...
    })
})

Increase

You can increase values in a channel metacounter by passing a NSDictionary<NSString *, NSNumber *> of items to increase as an argument to a parameter in the increaseMetaCounters:completionHandler: method. The values of corresponding keys in the metacounter will be incremented by the number you’ve specified.

Objective-C
Swift
Light Color Skin
Copy
[SBDOpenChannel getChannelWithUrl:CHANNEL_URL completionHandler:^(SBDOpenChannel * _Nonnull channel, SBDError * _Nullable error) {
    NSDictionary *deltaMetaCounters = @{@"key1": @(2),  // Increase by 2.
                    @"key2": @(3)};     // Increase by 3.

    [channel increaseMetaCounters:deltaMetaCounters completionHandler:^(NSDictionary * _Nullable metaCounters, SBDError * _Nullable error) {
        if (error != nil) {
            // Handle error.
        }

        ...
    }];
}];
Light Color Skin
Copy
SBDOpenChannel.getWithUrl(CHANNEL_URL, completionHandler: { (channel, error) in
    let deltaMetaCounters: NSDictionary = [
        "key1": 2, // Increase by 2.
        "key2": 3  // Increase by 3.
    ]

    channel?.increaseMetaCounters(deltaMetaCounters, completionHandler: { (metaCounters, error) in
        guard error == nil else {
            // Handle error.
        }

        ...
    })
})

Decrease

You can decrease values in a channel metacounter by passing a NSDictionary<NSString *, NSNumber *> of items to decrease as an argument to a parameter in the decreaseMetaCounters:completionHandler: method. The values of corresponding keys in the metacounter will be decremented by the number you’ve specified.

Objective-C
Swift
Light Color Skin
Copy
[SBDOpenChannel getChannelWithUrl:CHANNEL_URL completionHandler:^(SBDOpenChannel * _Nonnull channel, SBDError * _Nullable error) {
    NSDictionary *deltaMetaCounters = @{@"key1": @(3),  // Decrease by 3.
                    @"key2": @(4)};     // Decrease by 4.

    [channel decreaseMetaCounters:deltaMetaCounters completionHandler:^(NSDictionary * _Nullable metaCounters, SBDError * _Nullable error) {
        if (error != nil) {
            // Handle error.
        }

        ...
    }];
}];
Light Color Skin
Copy
SBDOpenChannel.getWithUrl(CHANNEL_URL, completionHandler: { (channel, error) in
    let deltaMetaCounters: NSDictionary = [
        "key1": 3, // Decrease by 3.
        "key2": 4  // Decrease by 4.
    ]

    channel?.decreaseMetaCounters(deltaMetaCounters, completionHandler: { (metaCounters, error) in
        guard error == nil else {
            // Handle error.
        }

        ...
    })
})

Retrieve

You can retrieve channel metacounter by creating a NSArray of keys to retrieve and passing it as an argument to a parameter in the getMetaCountersWithKeys:completionHandler: method. A NSDictionary<NSString *,NSNumber *> will return through the completionHandler with corresponding key-value items.

Objective-C
Swift
Light Color Skin
Copy
[SBDOpenChannel getChannelWithUrl:CHANNEL_URL completionHandler:^(SBDOpenChannel * _Nonnull channel, SBDError * _Nullable error) {
    NSArray *keys = @[@"key1", @"key2"];

    [channel getMetaCountersWithKeys:keys completionHandler:^(NSDictionary * _Nullable metaCounters, SBDError * _Nullable error) {
        if (error != nil) {
            // Handle error.
        }

        ...
    }];
}];
Light Color Skin
Copy
SBDOpenChannel.getWithUrl(CHANNEL_URL, completionHandler: { (channel, error) in
    let keys : NSArray = ["key1", "key2"]

    channel?.getMetaCounters(withKeys: keys, completionHandler: { (metaCounters, error) in
        guard error == nil else {
            // Handle error.
        }

        ...
    })
})

Delete

The process for deleting a metacounter is as simple as creating one.

Objective-C
Swift
Light Color Skin
Copy
[channel deleteMetaCountersWithKey:@"key1" completionHandler:^(SBDError * _Nullable error) {
    if (error != nil) {
        // Handle error.
    }

    ...
}];
Light Color Skin
Copy
channel.deleteMetaCounters(withKey: "key1", completionHandler: { (error) in
    guard error == nil else {
        // Handle error.
    }

    ...
})