You can access Buddycloud in many ways. This walkthrough will help you setup a Buddycloud-powered Android application with the ultimate goal of introducing you on how to exchange posts in a channel node, which is the most basic thing you can do with Buddycloud.

This example uses our REST API, which is better suited for mobile apps. You will need aid from the Pusher service in order to implement a push-to-pull schema in your Android app; communication to the Pusher service is done through the REST API.

Here is how this guide is meant to be used.

Setup flows

• To start building Buddycloud you will need a test account on the Dev-Console. We recommend using the developer console initially and later, you can install your own Buddycloud stack.

• The Using the API section simply explains the REST API calls involved in the flow of creating users and logging into Buddycloud as just-created/already-existing users.

  You can go ahead and implement these features into your app or simply simulate them through the console by issuing these HTTP calls via curl. You MUST at least create a user to keep going.

  Please note that the REST API uses the HTTP Basic authentication for passing user credentials.

  Please make sure you perform these operations when using the HTTP client library of your choice to make API calls (the code snippets below don't do it but that's because curl -u is already doing it for us).

• Then, once your Android application has a logged user to work with, the Using the Pusher section explains the next flow your app is supposed to take, which is to interact with both the Pusher service and Google Cloud Messaging in order to make your app able to receive Buddycloud updates regarding your logged user.

  As you will see by reading the official Android guides regarding GCM, some of these steps are meant to be performed once your Android application is opened and others everytime it is resumed.

  Obviously these steps can only be performed within your Android application! So you'll need to take the HTTP calls demonstrated in curl from this guide and use the HTTP client library of your choice in your app.

Usage flows

After setup, your Android application will end up with a logged Buddycloud user to work with and fully able to receive Buddycloud updates.

These are some of the cool things you can do once you've got that:

• Listening for incoming posts to a node...
• Fetching old posts from a node...
• Creating new post to a node...

Using the API

If you were to use your own Buddycloud domain now, to find the API endpoint of your domain, you'd go to your hosting console, then select your domain. Then the API endpoint for your domain would be listed among other endpoints.

But for this walkthrough you'll use the demo service, which means your app will talk to the demo service's API endpoint at starter.buddycloud.com/api.

Create a User

Many interactions with a given Buddycloud domain's REST API are only allowed with valid user credentials. For example, you need an user in order to register with the Pusher service (more about this very important service below). For this walkthrough you'll use a randomly-named Buddycloud account, which you'll create with help from the REST API.

The following API call creates this Buddycloud user account :

curl https://starter.buddycloud.com/api/account \
    -X POST \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d '{ \
          "username": "", \
          "password": "", \
          "email": "YOUR_EMAIL_HERE" \
    }'

Check User login credentials

You can check user credentials at any time simply by issuing the following API call:

curl https://starter.buddycloud.com/api/ \
    -u : \
    -X GET \
    -H "Accept: application/json"

If the HTTP call is successful, the credentials you sent are valid. You will need to safely store them within your Android app to proceed making further REST API calls using them!

Using the Pusher

For this walkthrough your Android app will register to the Pusher service that is used by the demo service. The Pusher is responsible for sending push notifications to the app.

Buddycloud updates are sent by the Pusher through Google Cloud Messaging, so that means your Android application must become a GCM Client in order to receive them.

Setup Google Play Services

Please refer to this guide in order to setup Google Play Services for your Android application.

Implement your Android app as a GCM Client

For this walkthrough, you don't need to create a Google API project, get API keys, build your own GCM servers, establish communication between them and your Buddycloud domains, etc.

All you need to do is implement your Android app as a GCM Client, as we are already taking care of the rest.

So please refer to this guide and perform steps 1 and 2 in order to make your Android app able to receive Buddycloud updates via GCM.

Register with the Pusher

Every registration with the Pusher service is associated with the logged user your Android application is working with. You can perform the steps below using hardcoded credentials or you can implement the flows explained in the Using the API section into your app and have the next steps below happen once a user logs into your Buddycloud-powered app.

Take advice from Step 3 of the guide above as it will help you on implementing your Android app as a GCM Client.

Get SENDER_ID from the Pusher

In the Register for GCM section, beware that instead of getting your own SENDER_ID from the Google API Console, in this walkthrough you'll just get the one associated with the demo Pusher service.

That's why you'll need the following call to the Buddycloud REST API:

curl https://starter.buddycloud.com/api/notification_metadata?type=gcm \
    -u : \
    -X GET \
    -H "Accept: application/json"

Which should give you a JSON like this as response:

{ "google_project_id": "USE_THIS_SENDER_ID" }

The value associated to the google_project_id key in the JSON response is the SENDER_ID your Android app should use to register for GCM.

Send REGISTRATION_ID to the Pusher

As instructed in Step 3 of that guide linked above, after registering for GCM, your Android app will be given a registration_id.

Finally, your Android app must use that registration_id to register with the Pusher server.

Use the following call to the REST API to do that:

curl https://starter.buddycloud.com/api/notification_settings \
    -u : \
    -X POST \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d '{ \
          "type": "gcm", \
          "target": "SENDER_ID_GOES_HERE" \
    }'

Within the payload of the call above you can specify the exact events you want to listen for incoming Buddycloud updates. Just add the events as keys with values being a boolean indicating whether or not you want updates of given event types.

For example, to be notified when your user is mentioned in another post or when there are new posts to nodes you are subscribed to, add the following key-value pairs to the payload before making the HTTP call:

{
        "type": "gcm",
        "target": "SENDER_ID_GOES_HERE",
        "postMentionedMe": "true",
        "postOnSubscribedChannel": "true"
}

These are all the events supported by the Pusher:

Exchanging posts

For the purposes of this walkthrough, you'll work with this specific node: [email protected]/posts.

You will subscribe to it, so that you receive updates when there are new posts to this node. Please have your Android app issue the following API call (or you can simply do it yourself manually via curl):

curl https://starter.buddycloud.com/api/subscribed \
    -u : \
    -X POST \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d '{ \
          "[email protected]/posts": "publisher" \
    }'

Now the logged user is subscribed to the node [email protected]/posts, thus the logged user has permission to listen for incoming updates, fetch old posts to this node or even create new posts to this node.

Listening for incoming posts

By performing the steps so far in this guide, you have properly empowered your Android application to be able to receive Buddycloud updates regarding the current logged user.

Before proceeding, please read this guide on how to receive GCM push notifications in general, as the same principles obviously apply for receiving Buddycloud updates through GCM. You will need a GCMIntentService similar to the one in that sample code snippet provided in that guide.

As you might recall, in previous steps in this walkthrough you've registered with the Pusher; while doing so you've indicated interest in receiving notifications for these particular events:

• When there are new posts to nodes the current logged user is subscribed to.
• When the current logged user is mentioned by others' posts.

That means your GCMIntentService will need to make sure it doesn't ignore incoming events with keys POST_ON_SUBSCRIBED_CHANNEL or MENTION.

The following code snippet shows how to make sure incoming push notifications are exactly the kind of Buddycloud updates you're listening for:

@Override
protected void onHandleIntent(Intent incomingPushNotif) {

  String pushMessage = incomingPushNotif.getStringExtra("message");
  String pushEvent = incomingPushNotif.getStringExtra("event");

  if ( pushEvent.equals("POST_ON_SUBSCRIBED_CHANNEL") ) {

    String author = incomingPushNotif.getStringExtra("AUTHOR_JID");
    String channel = incomingPushNotif.getStringExtra("CHANNEL_JID");
    String postedContent = incomingPushNotif.getStringExtra("CONTENT");

    /*
     * This means there is a new post to a node your user is subscribed to...
     * Handle this event as you wish!
     */

  }
  else if ( pushEvent.equals("MENTION") ) {

    String author = incomingPushNotif.getStringExtra("AUTHOR_JID");
    String channel = incomingPushNotif.getStringExtra("CHANNEL_JID");
    String postedContent = incomingPushNotif.getStringExtra("CONTENT");

    /*
     * This means there is a new post in which your user is mentioned...
     * Handle this event as you wish!
     */

  }

}

All types of Buddycloud GCM push notification event keys are listed in the third column of the table above.

Fetching old posts

Your Android app can fetch as many old posts as you want, potentially through several separate REST API calls.

The following REST API call accepts several query parameters that control exactly which portions of old posts you desire to receive.

• The max parameter specifies up to which amount of posts you want to get in each call.
• The after parameter, when present, means you want to retrieve only posts older than the post of given ID.

For example, to fetch the last 10 posts you can do:

curl https://starter.buddycloud.com/api/[email protected]/content/posts/threads?max=10 \
    -u : \
    -X GET \
    -H "Accept: application/json"

And you will get posts in a JSON format like this:

[
  {
    "id": "A_GIVEN_POST_ID",
    "author": "",
    "updated": "1595-06-01T12:00:00Z",
    "content": "This is a random post.",
    "media": null
  },
  ...
  {
    "id": "ANOTHER_GIVEN_POST_ID",
    "author": "",
    "updated": "1591-06-04T12:00:00Z",
    "content": "This is an older random post.",
    "media": null
  }
]

Then you can get posts older than the one of ID ANOTHER_GIVEN_POST_ID by issuing the following API call:

curl https://starter.buddycloud.com/api/[email protected]/content/posts/threads?max=10&after=ANOTHER_GIVEN_POST_ID \
    -u : \
    -X GET \
    -H "Accept: application/json"

Creating a new post

Finally, the following REST API call shall be used whenever the user your Android application is working with wishes to create a new post to one of the nodes it is subscribed to (e.g. [email protected]/posts):

curl https://starter.buddycloud.com/api/[email protected]/content/posts \
    -u : \
    -X POST \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -d '{ \
          "content": "Yet another random post, the newest!" \
    }'

Jumpstart

To get going you can also fork our ready-made demo app from http://github.com/buddycloud/buddycloud-android.