iOS
Channel Metadata

Channel Metadata

With metadata and metacounter, you can store additional information within a channel. The metadata allows you to store a NSDictionary of key-value pairs in a channel object. When you need an integer with atomic increasing and decreasing operations, use the metacounter instead of the metadata.

Use cases for the metadata and metacounters can be tracking the number of likes, the background color or a long description of a channel, which can each be fetched and rendered into the UI.


Create, update, retrieve, and delete a metadata

A metadata is a NSDictionary<NSString *, NSString *> that is stored within a channel. Its uses are flexible, allowing you to customize a channel to fit you and your users' needs.

Create

To store a metadata into a channel, create a NSDictionary<NSString *, NSString *>, add key-value pairs to it, and then pass it as a parameter when calling the createMetaData:completionHandler: method. You can store multiple key-value pairs in the dictionary.

Objective-C
Swift
Light Color Skin
Copy
[SBDOpenChannel getChannelWithUrl:channelUrl 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(channelUrl) { (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 process for updating a metadata is identical with the creation. Values are updated for existing keys, while new key-value pairs added.

Objective-C
Swift
Light Color Skin
Copy
[SBDOpenChannel getChannelWithUrl:channelUrl 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(channelUrl) { (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

To get stored key-value pairs in a metadata, create a NSArray of keys to retrieve, and then pass it as a parameter to the getMetaDataWithKeys:completionHandler: method. Through the completionHandler: callback, a NSDictionary<NSString *, NSObject *> containing the corresponding key-value pairs is returned.

Objective-C
Swift
Light Color Skin
Copy
[SBDOpenChannel getChannelWithUrl:channelUrl 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(channelUrl) { (channel, error) in
    let keys : NSArray = ["key1", "key2"]

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

Delete

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

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") { (error) in
    guard error == nil else {   // Error.
            return
    }
}

Create, update, increase, decrease, retrieve, and delete a metacounter

A metacounter is a NSDictionary<NSString *, NSNumber *> that is stored within a channel object. Its primary uses are to track and update discrete indicators within a channel.

Create

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

Objective-C
Swift
Light Color Skin
Copy
[SBDOpenChannel getChannelWithUrl:channelUrl 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(channelUrl) { (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 process for updating a metadata is identical with the creation. Values are updated for existing keys, while new key-value pairs added.

Objective-C
Swift
Light Color Skin
Copy
[SBDOpenChannel getChannelWithUrl:channelUrl 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(channelUrl) { (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

To increase the values of key-value pairs in a metacounter, create a NSDictionary<NSString *, NSNumber *> of pairs to increase, and then pass it as a parameter to the increaseMetaCounters:completionHandler: method, which increments the corresponding keys by the number you've specified.

Objective-C
Swift
Light Color Skin
Copy
[SBDOpenChannel getChannelWithUrl:channelUrl 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(channelUrl) { (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

To decrease the values of key-value pairs in a metacounter, create a NSDictionary<NSString *, NSNumber *> of pairs to decrease, and then pass it as a parameter to the decreaseMetaCounters:completionHandler: method, which decrements the corresponding keys by the number you've specified.

Objective-C
Swift
Light Color Skin
Copy
[SBDOpenChannel getChannelWithUrl:channelUrl 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(channelUrl) { (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

To get stored key-value pairs in a metacounter, create a NSArray of keys to retrieve, and then pass it as a parameter to the getMetaCountersWithKeys:completionHandler: method. A NSDictionary<NSString *,NSNumber *> which contains the corresponding key-value pairs is returned through the completionHandler callback.

Objective-C
Swift
Light Color Skin
Copy
[SBDOpenChannel getChannelWithUrl:channelUrl 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(channelUrl) { (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") { (error) in
    guard error == nil else {   // Error.
        return
    }
}