Guide to Subscriptions

Subscriptions are a powerful way for users to stay engaged with a community. A subscription to a conversation, a board, a category, or even a label, alerts users to activity important to them.

This section will teach you how to integrate subscription operations into an Android application through Community SDK APIs.

A subscription operates on a target -- the community, a category, a board, a topic message, or a label -- and each target is represented by a unique identifier. Users subscribe or unsubscribe to a single target for each subscription they create in the community.

In the following sections, you'll learn how to:

• Subscribe to a post
• Retrieve a user's subscriptions
• Unsubscribe from a target

Subscription API calls work similar to any other calls made through the Community Android SDK APIs. Each of the example tasks in this section include the following tasks:

• Creating a respective API-method client parameter
• Creating a respective API-method client
• Processing the client request, synchronously or asynchronously as needed
• Processing the response

Verifying that a user is logged in

All calls to our subscriptions API require authentication. Anonymous users cannot create or delete subscriptions.

Before you make any calls to the Subscription API, ensure that the current user is logged using this call on LiSDKManager:

    ```
    LiSDKManager.getInstance().isUserLoggedIn() == true
    ```

Subscribing to a topic message

Let's walk through creating a subscription to a message. Note that users subscribe to topic messages, not to replies or comments.

Create a target

The first thing we're going to do is create a subscription target using LiSubscriptionPostModel.MessageTarget(messageId), passing the message ID of the topic we're subscribing to.

LiSubscriptionPostModel also supports LiSubscriptionPostModel.BoardTarget.

    ```
    String messageId = "message:test";
    LiSubscriptionPostModel.Target target = new LiSubscriptionPostModel.MessageTarget(messageId);
    ```

Create a subscription POST model

Next, we're going to create a subscription POST model. This step puts the details for the subscription into the proper model for ingestion by the API when we make our POST call. We pass the target we created in the previous step.

    ```
    LiSubscriptionPostModel postModel = new LiSubscriptionPostModel(target);
    ```

Create a subscription parameter

Now, we create the parameters for the subscription that we will pass with our client request:

    ```
    LiClientRequestParams.LiPostSubscriptionParams params = new LiClientRequestParams.LiPostSubscriptionParams(mContext, target);
    ```

Create a post client and make a request

Finally, we're ready to create the POST client and make our request using LiClientManager.getSubscriptionPostClient(LiClientRequestParams). You can read more about getSubscriptionPostClient(LiClientRequestParams) in our API Reference guide and Javadoc.

Then, we make an asynchronous request.

    ```
    liClient = LiClientManager.getSubscriptionPostClient(params);
    liClient.processAsync(callback);
    ```

Processing the response

A successful response contains an instance of LiPostClientResponse, which contains a JSON body. It will look something like this:

{
    "status": "success",
    "message": "",
    "http_code": 200,
    "data": {
        "type": "subscription",
        "id": "0",
        "href": "/subscriptions/0",
        "target": {
            "type": "message",
            "id": "571",
            "href": "/messages/571",
            "view_href": "https://triumph.qa.lithium.com/t5/Cross-Device-Demo/A-new-question/m-p/571#M44"
        },
        "subscriber": {
            "type": "user",
            "id": "583464189",
            "href": "/users/583464189",
            "view_href": "https://triumph.qa.lithium.com/t5/user/viewprofilepage/user-id/583464189",
            "login": "Naren"
        }
    },
    "metadata": {}
}

The response returns a target (in this case, a message) and a subscriber (a user), and most important, the unique id of the subscription. You'll see how to use the value of id later when we look at how to unsubscribe from a target.

Retrieving a user's subscriptions

To retrieve all of a user's subscriptions, we're going to follow some familiar steps.

// We create the subscription parameters to use with the request
 LiClientRequestParams liClientRequestParams = new LiClientRequestParams.LiUserSubscriptionsClientRequestParams(mContext);
// We create a GET client and make the request
LiClient subscriptionsClient = LiClientManager.getUserSubscriptionsClient(liClientRequestParams);
        subscriptionsClient.processAsync(callback...);

Processing the response

On success, the response JSON will look something like the following. You'll see items similar to the ones returned from our earlier POST example.

{
  "status" : "success",
  "message" : "",
  "http_code" : 200,
  "data" : {
    "type" : "subscriptions",
    "list_item_type" : "subscription",
    "size" : 2,
    "items" : [ {
      "type" : "subscription",
      "id" : "32",
      "href" : "/subscriptions/32",
      "target" : {
        "type" : "message",
        "id" : "568",
        "href" : "/messages/568",
        "view_href" : "/t5/abc/A-new-question/m-p/568#M271"
      },
      "subscriber" : {
        "type" : "user",
        "id" : "583464189",
        "href" : "/users/583464189",
        "view_href" : "/t5/user/viewprofilepage/user-id/583464189",
        "login" : "Naren"
      }
    }, {
      "type" : "subscription",
      "id" : "30",
      "href" : "/subscriptions/30",
      "target" : {
        "type" : "message",
        "id" : "571",
        "href" : "/messages/571",
        "view_href" : "/t5/Cross-Device-Demo/A-new-question/m-p/571#M44"
      },
      "subscriber" : {
        "type" : "user",
        "id" : "583464189",
        "href" : "/users/583464189",
        "view_href" : "/t5/user/viewprofilepage/user-id/583464189",
        "login" : "Naren"
      }
    } ]
  },
  "metadata" : { }
}

Unsubscribing from a target

In this example, we're going to unsubscribe from the post we subscribed to earlier. To unsubscribe from a post necessarily needs a subscription ID which is obtained from the subscription. Subscriptions can be synced through Getting all subscriptions or a single subscription obtained as a response to subscribe call.

• Create a subscription delete client parameter

         String subscriptionId = "";
         LiClientRequestParams params = new LiClientRequestParams.LiDeleteSubscriptionParams(getContext(), subscriptionId);
  

• Create a delete subscription client and process

         LiClient client = new LiClientManager.getSubscriptionDeleteClient(params);
         client.processAsync(callback);
  

• Process the response

On success, the response would look like this:

{"status":"success","message":"","http_code":200,"data":{},"metadata":{}}