Channel Metadata

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

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


Create, update, retrieve, and delete a metadata

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

Create

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

[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;
        }
    }];
}];
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 metadata is identical with the creation. Values are updated for existing keys, while new key-value pairs added.

[SBDOpenChannel getChannelWithUrl:channelUrl completionHandler:^(SBDOpenChannel * _Nonnull channel, SBDError * _Nullable error) {
    NSDictionary *metaDataToUpdate = @{@"key1" : @"valueToUpdate1",
                @"key2" : @"valueToUpdate2"};

    [channel updateMetaData:metaDataToUpdate completionHandler:^(NSDictionary<NSString *,NSObject *> * _Nullable metaData, SBDError * _Nullable error) {
        if (error != nil) {     // Error.
            return;
        }
    }];
}];
SBDOpenChannel.getWithUrl(channelUrl) { (channel, error) in
    let metaDataToUpdate: NSDictionary = [
        "key1" : "valueToUpdate1",
        "key2" : "valueToUpdate2"
    ]

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

Retrieve

To get the stored metadata, create a NSArray of keys, and then pass it as an argument to getMetaDataWithKeys:completionHandler: method. The callback completionHandler returns a NSDictionary<NSString *, NSObject *> containing the corresponding key-value pairs.

[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;
        }
    }];
}];
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.

[channel deleteMetaDataWithKey:@"key1" completionHandler:^(SBDError * _Nullable error) {
    if (error != nil) {    // Error.
        return;
    }
}];
channel.deleteMetaData(withKey: "key1") { (error) in
    guard error == nil else {    // Error.
            return
    }
}

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

Metacounter is a <NSString *, NSString *> NSDictionary that is stored within a channel instance. Its primary uses are to track and update discrete indicators within a channel.

Create

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

[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;
        }
    }];
}];
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
        }
    })
}

Increase

The increase and decrease operations work similarly to getting metacounters, as described above. Create a NSArray of keys to pass to increaseMetaCounters:completionHandler: method, which increments the corresponding metacounters by the number you've specified.

[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;
        }
    }];
}];
SBDOpenChannel.getWithUrl(channelUrl) { (channel, error) in
    let deltaMetaCounters: NSDictionary = [
        "key1" : 2, // increases by 2
        "key2" : 3  // increased by 3
    ]

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

Decrease

Pass a NSArray of keys to decreaseMetaCounters:completionHandler: method, which decrements the metacounters by the number you've specified.

[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;
        }
    }];
}];
SBDOpenChannel.getWithUrl(channelUrl) { (channel, error) in
    let deltaMetaCounters: NSDictionary = [
        "key1" : 3, // decreases by 3
        "key2" : 4  // decreased by 4
    ]

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

Retrieve

To get the stored metacounters, create a NSArray of keys, and then pass it as an argument to getMetaCountersWithKeys:completionHandler: method. The callback completionHandler returns a NSDictionary<NSString *,NSNumber *> containing the corresponding key-value pairs.

[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;
        }
    }];
}];
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 metadata is as simple as creating one.

[channel deleteMetaCountersWithKey:@"key1" completionHandler:^(SBDError * _Nullable error) {
    if (error != nil) {    // Error.
        return;
    }
}];
channel.deleteMetaCounters(withKey: "key1") { (error) in
    guard error == nil else {    // Error.
        return
    }
}