Managing tags and interests (channels)

Each bitplace can be assigned zero or more tags that convey information about the attributes associated with it. Tags in the Bitplaces service can be of several types, and an arbitrary number of types can be configured in the backend. The category type is a particularly interesting one for your application. Your app can configure the categories from which the SDK should receive location events and messages based on either the known user interests or the categories explicitly selected by the user.

Tags are represented by the Tag class. A tag consists of an ID, a name and a type ID (categories being only one particular type of tag), among other attributes. Tag API documentation for a complete list of the provided properties.

Retrieving tag types and all of the tags from a given type

Before you retrieve a list of tags from the backend you need to select a tag type. To fetch the available tag types use the following method:

1
getTagTypes(BitplacesOperationCompletionHandler<ArrayList<TagType>> completionHandler);

Your completion handler will be invoked when the operation is completed with a list of TagType instances.

TagType exposes the following getters to access its data:

Method Return value type Description
getId() long ID of the tag type.
getName() String Name of the tag type.

EXAMPLE: Requesting tag types

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
BitplacesSDK bpSDK = BitplacesSDK.getInstance();
bpSDK.getTagTypes(
    new BitplacesOperationCompletionHandler<ArrayList<TagType>>() {
        @Override
        public void onOperationComplete(int resultCode, ArrayList<TagType> tagTypes) {
            if (BitplacesSDK.ResultCode.fromCode(resultCode).isSuccessful()) {
                Log.i(TAG, "Received " + tagTypes.size() + " tag types");
                // store the received tags types to use them later when requesting tags by type
                // [...]
            } else {
                Log.e(TAG, "An error prevented the tag type list from being retrieved");
            }
        }
    });

Once you know the tag types available and their IDs, you can request tags of a specific type with this method.

1
getTagsByTagType(long tagTypeId, BitplacesOperationCompletionHandler<ArrayList<Tag>> completionHandler)

Alternatively, if you know the exact name of the tag type you will be requesting tags for, you may request tags directly by tag type name with the help of this method:

1
getTagsByTagType(String tagTypeName, BitplacesOperationCompletionHandler<ArrayList<Tag>> completionHandler)

The tagTypeName string parameter will be compared against all of the tag type names available for your account in a case insensitive manner.

For any of the two getTagsByTagType() methods your specified completionHandler will be invoked with a list of Tag instances when the operation is completed.

EXAMPLE: Requesting tags by tag type name

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
BitplacesSDK bpSDK = BitplacesSDK.getInstance();
bpSDK.getTagsByTagType("categories", new BitplacesOperationCompletionHandler<ArrayList<Tag>> () {
    @Override
    public void onOperationComplete(int resultCode, ArrayList<Tag> tags) {
        if (ResultCode.fromCode(resultCode).isSuccessful()) {
            Log.i(TAG, "Received " + tags.size() + " tags");
                // do something with the received tags...
            } else {
                Log.e(TAG, "An error prevented the tag list from being retrieved");
        }
    }
});

Tag exposes the following getters to access its data:

Method Return value type Description
getId() long ID of this tag on the Bitplaces platform
getName() String Name of this tag
getType() Tag.TagType One of the following: TagType.NAME, TagType.KEYWORD or TagType.CATEGORY
getForeignId() String Your set foreign ID for this tag
getParentId() long ID of this tag's parent
getExtraAttributes() Map<String, Object> A map of arbitrary key-value pairs associated with the tag.

Also, you can fetch a list of tag IDs corresponding to another list of tag names by using the following instance method:

1
getTagIdsByTags(String[] tagNames, TagType tagType, BitplacesOperationCompletionHandler<long[]> completionHandler)

The usage of this method is almost identical to that of the getTagsByTagType() operation, with the following differences:

  • This method's first parameter is an array of tag names whose IDs will be retrieved and provided to your callback handler.
  • Your callback handler will receive an array of longs containing the retrieved IDs.

Subscribing to interests

You can save and retrieve the user's interests, expressed as subscriptions to channels, to and from the Bitplaces platform. Channels are just a particular type of Tag representing the categories and topics the user is interested in. This will affect which bitplaces will trigger events for this user, as well as which broadcast notifications will this instance of your app receive as push and inbox messages.

There are three broad kinds of channel subscriptions available to the user:

  • No specific channels: the user subscribes only to messages coming from Channel Independent Bitplaces.
  • All channels: the user subscribes to notifications coming from all channels.
  • Selected channels: the user can express his or her preferences for some channels.

The maximum amount of channels that a given user can be subscribed to at once, using the selected channels subscription mode, is limited to a number which you can retrieve from the backend in the following way:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
BitplacesSDK bpSDK = BitplacesSDK.getInstance();

bpSDK.getUAPreferenceSettings(new BitplacesOperationCompletionHandler<UAPreferenceSettings>() {
    @Override
    public void onOperationComplete(int resultCode, UAPreferenceSettings retrievedSettings) {
        if (BitplacesSDK.ResultCode.fromCode(resultCode).isSuccessful()) {
            int subscriptionLimit = retrievedSettings.getMaxChannelCount();
        } else {
            // Use the last known value, or deal with the error in a way
            // that makes sense within your application logic.
        }
    }
});

In the example above the maximum amount of subscriptions is delivered encapsulated in a UAPreferenceSettings instance. Use its getMaxChannelCount() getter method to read its value.

To set the user's subscription preferences in the Bitplaces backend:

  • Initialize first a ChannelPreferences instance with the desired subscription preference mode and, if the mode is SELECTED_CHANNELS, provide a collection of Long values corresponding to the desired channel IDs.
    • The subscription preference mode can be any of the following values defined in ChannelPreferences.ChannelSelectionPreference:
      • CIB_ONLY, corresponding to the no specific channels case, where the user subscribes only to notifications coming from Channel Independent Bitplaces and general broadcasts.
      • ALL_CHANNELS, corresponding to the case where the user subscribes to notifications coming from all channels.
      • SELECTED_CHANNELS, corresponding to the case where the user explicitly subscribes to a limited number of interests. The user will still keep receiving notifications from Channel Independent Bitplaces and general broadcasts. If this mode is selected, you must provide a Collection of channel IDs corresponding to the user's selection.
  • Call BitplacesSDK's setChannelPreferences() instance method, passing to it your ChannelPreferences instance and, because the operation involves an asynchrolously performed network call, a completionHandler that will be invoked with its result.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
    Collection<Long> channelIds = new ArrayList<Long>(5);
    channelIds.add(1931L);
    channelIds.add(1981L);
    channelIds.add(1940L);
    channelIds.add(1999L);
    channelIds.add(1998L);

    ChannelPreferences channelPreferences =
        new ChannelPreferences(ChannelPreferences.ChannelSelectionPreference.SELECTED_CHANNELS,
                               channelIds);

    BitplacesSDK bpSDK = BitplacesSDK.getInstance();

    bpSDK.setChannelPreferences(channelPreferences, new BitplacesOperationCompletionHandler<ChannelPreferences>() {
        @Override
        public void onOperationComplete(int resultCode, ChannelPreferences setPreferences) {
            if (BitplacesSDK.ResultCode.fromCode(resultCode).isSuccessful()) {
                // The preferences were successfully set.
            } else {
                // There was an error when setting the preferences.
                // Retry in a way that makes sense within your application logic.
            }
        }
    });

You can retrieve the current user's subscription preferences with the BitplacesSDK's getChannelPreferences() instance method.

If the subscription preferences are in the selected channels mode, you can access the selected channels via getSelectedChannels(), which returns a Collection of Tag instances corresponding to the subscribed channels.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
BitplacesSDK bpSDK = BitplacesSDK.getInstance();

bpSDK.getChannelPreferences(new BitplacesOperationCompletionHandler<ChannelPreferences>() {
    @Override
    public void onOperationComplete(int resultCode, ChannelPreferences retrievedPreferences) {
        if (BitplacesSDK.ResultCode.fromCode(resultCode).isSuccessful()) {
            // The preferences were successfully retrieved.
            if (retrievedPreferences.getSelectionPreference() == SELECTED_CHANNELS) {
                Collection<Tag> selectedChannels = retrievedPreferences.getSelectedChannels();
                // ...
            }
        } else {
            // There was an error when retrieving the preferences.
            // Retry in a way that makes sense within your application logic.
        }
    }
});