iOS
User Channel Metadata

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

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<NSString *,NSString *> * _Nullable metaData, SBDError * _Nullable error) {
    if (error != nil) { // Error.
        return;
    }
}];
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 {   // Error.
        return
    }
})

Update

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<NSString *,NSString *> * _Nullable metaData, SBDError * _Nullable error) {
    if (error != nil) { // Error.
        return;
    }
}];
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 {   // Error.
        return
    }
})

Retrieve

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

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) { // Error.
        return;
    }
}];
Light Color Skin
Copy
let user = SBDMain.getCurrentUser()!

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

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

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<NSString *,NSString *> * _Nullable metaData, SBDError * _Nullable error) {
        if (error != nil) {     // Error.
            return;
        }
    }];
}];
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 {   // Error.
            return
            }
    })
})

Update

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<NSString *,NSObject *> * _Nullable metaData, SBDError * _Nullable error) {
        if (error != nil) {     // Error.
            return;
        }
    }];
}];
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 {   // Error.
            return
            }
    })
})

Retrieve

You can retreive 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<NSString *,NSObject *> * _Nullable metaData, SBDError * _Nullable error) {
        if (error != nil) {     // Error.
            return;
        }
    }];
}];
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 {   // Error.
            return
        }
    })
})

Delete

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) { // Error.
        return;
    }
}];
Light Color Skin
Copy
channel.deleteMetaData(withKey: "key1", completionHandler: { (error) in
    guard error == nil else {   // Error.
            return
    }
})

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<NSString *,NSNumber *> * _Nullable metaCounters, SBDError * _Nullable error) {
        if (error != nil) { // Error.
            return;
        }
    }];
}];
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 {   // Error.
            return
        }
    })
})

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<NSString *,NSNumber *> * _Nullable metaCounters, SBDError * _Nullable error) {
        if (error != nil) {     // Error.
            return;
        }
    }];
}];
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 {       // Error.
            return
        }
    })
})

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),  // Increases by 2.
                    @"key2": @(3)};     // Increases by 3.   

    [channel increaseMetaCounters:deltaMetaCounters completionHandler:^(NSDictionary<NSString *,NSNumber *> * _Nullable metaCounters, SBDError * _Nullable error) {
        if (error != nil) { // Error.
            return;
        }
    }];
}];
Light Color Skin
Copy
SBDOpenChannel.getWithUrl(CHANNEL_URL, completionHandler: { (channel, error) in
    let deltaMetaCounters: NSDictionary = [
        "key1": 2, // Increases by 2.
        "key2": 3  // Increases by 3.
    ]

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

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),  // Decreases by 3.
                    @"key2": @(4)};     // Decreases by 4.

    [channel decreaseMetaCounters:deltaMetaCounters completionHandler:^(NSDictionary<NSString *,NSNumber *> * _Nullable metaCounters, SBDError * _Nullable error) {
        if (error != nil) { // Error.
            return;
        }
    }];
}];
Light Color Skin
Copy
SBDOpenChannel.getWithUrl(CHANNEL_URL, completionHandler: { (channel, error) in
    let deltaMetaCounters: NSDictionary = [
        "key1": 3, // Decreases by 3.
        "key2": 4  // Decreases by 4.
    ]
    
    channel?.decreaseMetaCounters(deltaMetaCounters, completionHandler: { (metaCounters, error) in
        guard error == nil else {   // Error.
            return
        }
    })
})

Retrieve

You can retreive 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<NSString *,NSNumber *> * _Nullable metaCounters, SBDError * _Nullable error) {
        if (error != nil) { // Error.
            return;
        }
    }];
}];
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 {   // Error.
            return
        }
    })
})

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) { // Error.
        return;
    }
}];
Light Color Skin
Copy
channel.deleteMetaCounters(withKey: "key1", completionHandler: { (error) in
    guard error == nil else {   // Error.
        return
    }
})