Note
The subscriber feature included in this SDK is a beta version. It is prohibited to create master software that includes this feature. API specifications and limitations may change at a later point.
The subscriber feature is a messaging feature implemented using a publish-subscribe messaging model. Message senders post messages called content to special channels called topics that include a particular topic of discussion. Message receivers can then retrieve content from any topic of interest.(Fig. 7.1) Users can also follow one or more topics of interest and automatically get content posted to those topics in a chronological digest.(Fig. 7.2) This chronological digest of content is called a timeline. A unique timeline is created for each user. Content data comprises a content ID, an arbitrary string (up to SubscriberConstants::MAX_CONTENT_MESSAGE_LEN
characters in length), arbitrary binary data (up to SubscriberConstants::MAX_CONTENT_BINARY_SIZE
in size), the principal ID of the user who posted the content, the topics that include the content, and the post date and time. A single piece of content can be posted to multiple topics. Although polling techniques are prohibited in the standard NEX APIs, the use of polling techniques is permitted in APIs for receiving content. For more information, see Getting the Content from a Topic and Getting the Timeline.
Figure 7.1. Getting Content From a Topic
Figure 7.2. Getting Content From the Timeline
The subscriber feature is intended for use cases such as the following.
The general workflow for using the subscriber feature is as follows.
Use the SubscriberClient
service client. Initialization and finalization of the SubscriberClient
object works the same as it does for the matchmaking service client. (For more information, see 4.3.)
After a user follows a topic, content posted to that topic starts appearing in the user's timeline. A maximum of SubscriberConstants::NUM_RESERVED_TOPICS
topics is available in advance, and users can follow whichever topics they like. A single user can follow up to SubscriberConstants::MAX_FOLLOWING_SIZE
topics. There is no limit on the number of users that can follow a single topic. Users can unfollow a topic if they lose interest in it and no longer want content posted to that topic to appear in their timelines. Following or unfollowing topics does not affect anything other than the timelines of followers. You can post content to a topic, get the content posted to a topic, and get the followers of a topic all without following the topic. Following and unfollowing topics simply updates the user's timeline accordingly. Content from topics that the user has followed is included in the user's timeline, and content from topics that the user has unfollowed is removed from the user's timeline.
Use the SubscriberClient::Follow
function to follow a topic. Use the SubscriberClient::Unfollow
or the SubscriberClient::UnfollowAll
function to unfollow a topic. Use the SubscriberClient::Follow
function when you want to add a new topic to the list of topics a user is already following. Use the SubscriberClient::UnfollowAllAndFollow
function when you want to follow only specified topics regardless of whatever topics are currently being followed. Generally, the latter function is only used after logging in to the game server when you need to synchronize the list of topics being followed between the client and the server based on the client information. If you want to update the client information based on the list of topics being followed on the server instead, use the SubscriberClient::GetFollowing
function to get the list of topics a user is currently following.
Specify topics as strings formatted as shown below.
"r/<reserved topic number>"
Reserved topic numbers range from 0 to (SubscriberConstants::NUM_RESERVED_TOPICS
- 1). In other words, you can use "r/0," "r/1,"and so on through "r/127." Use the SubscriberUtil::ReservedTopicNumToTopicString
function to convert a reserved topic number to a properly-formatted topic string. Use the SubscriberUtil::TopicStringToReservedTopicNum
function to convert a topic string to a reserved topic number.
Use the SubscriberClient::PostContent
function to post content to a topic. You can specify to post content to multiple topics. At least one topic must be specified. After content is successfully posted to a topic, it starts appearing in the timelines of users following that topic. Each piece of content posted to topic is assigned a content ID. Content IDs are incremented each time content is posted.
Use the SubscriberClient::GetContent
function to get the content from the specified topic. Users do not need to be following a topic to get the content for that topic. Up to SubscriberConstants::MAX_TOPIC_CONTENT_SIZE
pieces of content can be stored in a topic at one time.
Content retrieved from a topic is listed in decreasing order by content ID. Content IDs are issued in the order that the content is posted and are strictly increasing. The post date and time included in the content may be off by several seconds, however. Note that these timestamps may not reflect the exact order in which content was posted. Content with a smaller ID than the content with the largest ID that was obtained the last time content was retrieved may be inserted later due to differences in processing time on the server. For example, if after retrieving the content from a topic once you had two pieces of content with IDs 3 and 1, you could potentially get three pieces of content with IDs 3, 2, and 1 if you retrieve the content from the same topic again later.
In some cases, you may be able to call the SubscriberClient::GetContent
function with a frequency outside of the call frequency range specified in the guidelines. For the limits on call frequency for this function, see the guidelines. However, stop polling and avoid unnecessary access as much as possible if you transition to a scene where the information that is retrieved with this function is not used.
Use the SubscriberClient::GetTimeline
function to get the timeline, which contains a chronological digest of content posted to the topics that the user is following. Up to SubscriberConstants::MAX_TIMELINE_CONTENT_SIZE
pieces of content can be stored in the timeline at any one time.
Content retrieved from a topic is listed in decreasing order by content ID. Content IDs are issued in the order that the content is posted and are strictly increasing. The post date and time included in the content may be off by several seconds, however. Note that these timestamps may not reflect the exact order in which content was posted. Content with a smaller ID than the content with the largest ID that was obtained the last time content was retrieved may be inserted later due to differences in processing time on the server. For example, if after retrieving the content from a topic once you had two pieces of content with IDs 3 and 1, you could potentially get three pieces of content with IDs 3, 2, and 1 if you retrieve the content from the same topic again later.
If a single piece of content is posted to multiple topics and the user is following more than one of those topics, that content is merged and stored as a single entry in the timeline. The function gets a blank content object if the user has not followed any topics. In addition to getting the local user's timeline, you can also specify the principal IDs of other users to get their timelines. If users are following a topic to which content is posted very frequently, their timelines may get filled with content just from that topic. As a result, use the SubscriberClient::GetContent
function rather than the timeline to get content from topics to which content is posted very frequently.
In some cases, you may be able to call the SubscriberClient::GetTimeline
function with a frequency outside of the call frequency range specified in the guidelines. For the limits on call frequency for this function, see the guidelines. However, stop polling and avoid unnecessary access as much as possible if you transition to a scene where the information that is retrieved with this function is not used.
Use the SubscriberClient::DeleteContent
function to delete content that the local user posted previously. To delete content, you must specify the content ID and the topics it was posted to. If a user specified three topics when the content was posted, for example, all three topics would need to be specified when deleting the content for it to be deleted from all of them. Specify a single topic if you want to delete the piece of content from that topic only. In this case, the piece of content would remain untouched in the other two topics. Users cannot delete content posted by other users. Content cannot be explicitly deleted from the timeline. However, any content that was previously in the timeline will be removed the next time the timeline is updated if the content itself is deleted from the corresponding topics. The timeline is updated at the following times.
It will also be possible to delete content from NMAS at some point in the future.
Error handling is the same as for matchmaking. For more information, see Section 4.25 Error Handling. The errors that can occur when using the subscriber feature are listed in Table 7.1. The API functions that return these errors are listed in the function reference. This table excludes shared errors that occur during NEX communication, and so on.
ReturnCode Value |
Description |
---|---|
QERROR(Subscriber, Unknown) | Unknown error. This error could be caused by an unexpected server error. |
QERROR(Subscriber, InvalidArgument) | Invalid argument. This error is caused by an implementation error. |
QERROR(Subscriber, OverLimit) | The number of followed topics is over the limit. Exceeds the maximum number of followers that can be retrieved at one time. Occurs when the message or binary data included in posted content is too large. This error is caused by an implementation error. |
QERROR(Subscriber, PermissionDenied) | Attempted to delete content that was posted by another user. This error is caused by an implementation error. |
CONFIDENTIAL