Building Social Apps Using Yammer JavaScript SDK
In the last chapter, you learned about the Yammer REST web service interface and learned how to use Yammer REST APIs in your business applications. In this chapter, you will learn about the Yammer SDKs released by Yammer. Yammer has released the following SDKs specifically for developers to build on the Yammer platform:
Yammer SDKs are open source code, which enables you to access Yammer APIs from various technology platforms. Yammer SDKs enable developers to include Yammer authentication and integrate Yammer data into their business applications using client-side and server-side code.
In this chapter, we’re going to use Yammer’s JavaScript SDK to integrate Yammer with HTML-based enterprise business applications.
Note SDK (Software Development Kit) is a programming kit that includes platform APIs, programming tools, and help documentation that allows developers to develop applications for a specific platform.
Introduction to the JavaScript SDK
Let’s start working with Yammer’s JavaScript SDK. The Yammer JavaScript SDK allows developers to integrate Yammer into JavaScript-enabled applications using its rich set of functions for adding social plugins, making API calls, and implementing the Yammer login. The JavaScript SDK provides the following features:
JavaScript SDK includes a rich set functions that allow developers to integrate line-of-business applications with Yammer.
Before we implement the Yammer JavaScript SDK, let’s explore the setup that’s required to use the SDK for integrations and learn how to configure authentication to Yammer from a business application using Yammer’s JavaScript SDK functions.
Setup Required to Use the JavaScript SDK
Let’s first explore the very basic setup required to use Yammer JavaScript SDK so it can integrate with external applications. The Yammer SDK for JavaScript doesn’t have to be downloaded or installed. Instead you simply need to include a short piece of regular JavaScript code located on Yammer server (https://c64.assets-yammer.com/assets/platform_js_sdk.js) in your HTML. That will load the SDK on to your web pages or application interface.
The Yammer SDK reference is available at:
https://c64.assets-yammer.com/assets/platform_js_sdk.js
Note At the time of writing this book, c64 is the version released by Yammer. You should refer to the Yammer developer documentation for the latest SDK versions.
The following snippet of code shows the basic version of the JavaScript SDK. You should insert it in the <head> tag on each page you want to load it.
<script type="text/javascript" data-app-id="YOUR-APP-CLIENT-ID" src="https://c64.assets-yammer.com/assets/platform_js_sdk.js"></script>
This script will load and initialize the SDK. You must replace the value in data-app-id with the ID of your own Yammer App. You can find this ID using the client https://www.yammer.com/client_applications, as explained in Chapter 3.
Another important configuration is the JavaScript origins section of your Yammer app’s configuration. An origin is the URL of your web application, SharePoint site, or SharePoint-hosted app.
You need to enter all the URLs of your line-of business-applications. In our case study, this would be the SPDS University SharePoint-hosted app. It’s URL could be https://spdsuniversity.sharepoint.com/sites/Dev or https://SPDS University-1a08e7eeb36b03.sharepoint.com/sites/Dev.
That’s all that is required from a setup point of view. In the next section, we will take a closer look at JavaScript SDK’s authentication functions. You will learn about other JavaScript SDK’s functions that allow you to call Yammer REST APIs from your line-of-business applications.
Authentication Using JavaScript SDK
The Yammer’s JavaScript SDK provides a secure way to authenticate Yammer users in external applications. Yammer’s JavaScript SDKs can be leveraged in a variety of applications, including HTML sites, web applications, Windows 8 apps, and SharePoint-hosted app on the Microsoft platform. In Chapter 4, you built a SPDS University SharePoint-hosted app for SharePoint Online using the JavaScript SDK to authenticate the Yammer users. In this section, we will extend the functionality of that app to post and retrieve data from Yammer by using the JavaScript SDK.
First, let’s explore the different authentication functions provided by the Yammer JavaScript SDK.
Authentication Functions
The Yammer JavaScript SDK includes core authentication functions to authenticate users and retrieve user data from Yammer into your line-of-business applications. The core authentication functions are the heart of the Yammer JavaScript SDK and easily can be invoked from client-side HTML code. Table 7-1 lists all the available authentication functions in the Yammer JavaScript SDK.
Table 7-1. Yammer JavaScript SDK’s Authentication Functions
Function |
Table Head |
---|---|
yam.platform.loginButton |
Provides a “Log In with Yammer” button using simple HTML markup. |
yam.platform.GetLoginStatus |
Returns the Yammer user’s login status and, if user is already logged in, it returns the access token. |
Yam.platform.logout |
This function is used to log out the logged in user. |
yam.platform.login |
Invokes the Yammer Login window in a popup. Ensure that you call this function inside a function(response) within getLoginStatus. |
In the following section, you will learn more about each of the authentication functions listed in Table 7-1.
The simplest way to implement OAuth 2.0 authentication flow is to use the “Sign In with Yammer” button. You pass a selector parameter in the login function and second parameter is a callback function to handle the response. The HTML element such as <span id="yammer-login"></span> gets converted into a standard “Sign In with Yammer” button, as shown in Figure 7-1.
Figure 7-1. Sign In with Yammer button
Let’s look at the syntax and parameters of the loginButton function.
Here is the syntax of the loginButton function:
yam.platform.loginButton(''#yammer-login'', [callback])
The loginButton function uses two parameters, listed in Table 7-2.
Table 7-2. loginButton Function Parameters
Name |
Type |
Required |
---|---|---|
#selector |
HTML element name as string |
Yes |
[callback] |
Function |
Yes |
The complete implementation of the loginButton function is provided in the following code snippet:
<span id="yammer-login"></span>
<script>
yam.connect.loginButton('#yammer-login',
function (resp) {
if (resp.authResponse) {
displayAuthResult(resp);
}
});
</script>
When this button is clicked by user, it initiates the OAuth authentication workflow on Yammer. When the user approves or denies the Yammer app, the callback function will execute. To determine whether the user has logged in and has approved your Yammer app, you can check the resp.authResponse property value.
If the user isn’t logged into your application or isn’t logged into Yammer, you can use the Login window to prompt them to do both. If the user isn’t logged into Yammer, he will first be prompted to log in. If he is accessing Yammer for the first time, he will be asked to grant permission to the Yammer app to access his data, as shown in Figure 7-2.
Figure 7-2. Validation by Yammer to allow an external application to use the user’s data
Function: getLoginStatus
The JavaScript SDK function getLoginStatus can be called to determine whether the user is already logged into Yammer. The GetLoginStatus function takes two parameters—a callback function and Boolean parameter (true or false) to forceRefresh. When getLoginStatus is called for the first time, it calls the Yammer API. After a successful call, the callback function will be triggered. The server response is passed to the callback function.
Here is the syntax of the getLoginStatus function:
yam.platform.getLoginStatus(callback, [forceRefresh])
The getLoginStatus function uses two parameters, listed in Table 7-3.
Table 7-3. getLoginStatus Function Parameters
The complete implementation of the getLoginStatus() function is provided in the following code snippet
1. <script>
2. yam.connect.getLoginStatus(
3. function(response)
4. {
5. if(response.authResponse){
6. alert("Already Logged in");
7. callback();
8. }
9. else
10. {
11. alert("Not Logged in");
12. yam.platform.login(function(response)
13. {
14. // Hanlde Resposne here
15. };
16. });
17. </script>
Note You do not need to store the access token, as subsequent calls to yam.platform.request() will automatically use the token returned by this call.
Let’s explore this code snippet line by line:
Function: login
The yam.platform.login() function is an alternative way to trigger the Yammer login pop-up. This is different from the “Sign In with Yammer” button, which we explained earlier.
Here’s the syntax of the login function:
yam.platform.login([opts], [callback])
The login function uses two parameters, listed in Table 7-4.
Table 7-4. The login Function’s Parameters
Function |
Description |
---|---|
[opts] |
Object |
[callback] |
Function |
Yam.platform.login() can be used with a GetLoginStatus() method, as shown in the following example:
yam.getLoginStatus(
function(response) {
if (response.authResponse) {
console.log("logged in");
console.dir(response); //print user information to the console
}
else {
yam.platform.login(function (response) { //prompt user to login and authorize your app, as necessary
if (response.authResponse) {
console.dir(response); //print user information to the console
}
});
}
}
);
You should call the yam.platform.login() method inside a function(response) within getLoginStatus(), as shown in this example. The yam.platform.login() function prompts the user to log in using the Yammer Login screen and then the authorization screen appears so you can authorize your app. Once users take action, the pop-up is closed and the callback function is triggered.
Function: logout
The logout() function enables users to log out from Yammer directly from their business applications. You can check the login status of the user before calling this function, which will ensure that all components required for logout function are loaded.
The syntax of the logout function is as follows:
yam.platform.logout([callback])
The logout function uses one parameter, explained in Table 7-5.
Table 7-5. The logout Function Parameters
Implementation of the logout function is very simple, as illustrated in the following code snippet:
yam.platform.logout(function (response) {
// write your code here
})
So, now you have learned the various authentication functions provided by the Yammer JavaScript SDK to implement the authentication using OAuth 2.0 flow in your line-of-business applications. Next, you will learn about calling Yammer REST APIs using JavaScript SDKs.
Using the JavaScript SDK to Call Other REST APIs
Once you implement the authentication using OAuth 2.0 flow, you need to call the Yammer REST APIs to write or read data from Yammer in your business applications. Let’s explore the functions provided by the JavaScript SDK to make REST APIs calls.
Additional Functions
The Yammer JavaScript SDK includes functions that allow developers to retrieve data from Yammer into their line-of-business applications. Table 7-6 lists the function in Yammer JavaScript SDK.
Table 7-6. Yammer JavaScript SDK’s Additional Function
Function |
Table Head |
---|---|
yam.platform.request |
This function can be used to call all other Yammer REST APIs. |
In the following section, you will learn about the yam.platform.request function in more detail.
Function: request
The Yammer JavaScript SDK also provides a function that can be used to call other REST APIs. This function can be used to read or write data to Yammer. For example, to post a message to a Yammer group or to post a private message on behalf of a user, you use the JavaScript SDK’s yam.platform.request() method to call all the REST APIs.
Here’s the syntax of the yam.platform.request function:
yam.platform.request(options)
The yam.platform.request() takes one parameter—Option—which contains four sub-parameters, as listed in Table 7-7.
Table 7-7. yam.platform.request Function Parameters
The yam.platform.request() makes Yammer API calls with a bearer token for the current users. The bearer token is set using the yam.platform.setAuthToken() method.
The complete implementation of the yam.platform.request function is provided in the following code snippet:
yam. platform.request({
url: "messages.json",
method: "GET",
success: function (msg) {
console.dir ("Get was Successful!: " + msg);
},
error: function (msg)
{
console.dir(msg);
}
})
You can make calls to the REST API without the hostname, as shown in the previous example. The previous example uses url:message.json instead of a complete hostname like https://api.yammer.com/api/v1/ messages.json. When calling REST APIs through the JavaScript SDK, you will need to use the api.yammer.com as documented on https://developer.yammer.com/yammer-sdks/.
In Exercise 7-1, you will learn to integrate SharePoint-hosted apps with Yammer using JavaScript SDK. Exercise 7-1 is an extension of Exercise 4-2. In Exercise 4-2, you learned how to implement OAuth 2.0 authentication, which uses JavaScript SDK’s authentication function discussed in this chapter. So before you start Exercise 7-1, go back and work through Exercise 4-2 if you have not already done so.
Implementing Yammer Integration in a SharePoint-Hosted App Using JavaScript SDK
In Exercise 7-1, you will implement Yammer integration in a SharePoint-hosted app using JavaScript SDK. You need Visual Studio 2012 Professional or higher and Office Developer Tools for Visual Studio 2012. These can be downloaded from http://msdn.microsoft.com/en-us/office/apps/fp123627.
EXERCISE 7-1: MESSAGES MANAGEMENT: POST A MESSAGE TO A YAMMER GROUP
In this exercise, we will extend the functionality of the SharePoint-hosted app we built in Exercise 4-2 by adding more social features to it in order to post messages and so on.
<div style="position: absolute; top: 510px; left: 20px; width: 300px; height:80px; background-color: azure; border:dotted; border-width:medium">
<br />
<input type="text" id="txtmessage" value="hi" style="width:250px; height:20px;" />
<br />
<input type="button" onclick="postAMessage()" value="Post Message to Yammer" />
</div>
function postAMessage() {
var ItemURL = "https://SPDSpetro.sharepoint.com/";
var group_id = 4966305;
var message = document.getElementById('txtmessage').value
postMessagetoYammer(ItemURL, message, group_id);
}
This function calls the PostMessagetoYammer function, defined in the YammerCore.js, by passing the ItemURL, the message, and the group_id.
The group_id is hard-coded in this example; however, you can use the message retrieval REST API to get the group_Id to post a message to group.
Figure 7-3. Add a new JavaScript file and name it YammerCore.js
function postMessagetoYammer(ItemURL, message, group_id) {
var testMessage = { "body": "Hello Test, have you seen this" + ItemURL };
yam.platform.request({
url: "https://api.yammer.com/api/v1/messages.json",
method: "POST",
data: {
"body": testMessage,
"group_id": group_id
} ,
success: function (msg) {
console.log("Message Posted Successfully");
},
error: function (msg) {
console.log("Message Posting Error: " + msg.statusText);
}
});
}
Note As you are using Yammer SDK, you do not need to set the header for the bearer token. The Yammer SDK does it for your and generates the request header with the authentication bearer retrieved by using the OAuth flow.
<script src="../Scripts/yammercore.js"></script>
Messages Management: Like a Message
Note Yammer JavaScript SDK provides the following REST API to mark a message as liked by the current user. https://www.yammer.com/api/v1/messages/liked_by/current.json?message_id=[:id]
Where the ID represents the target message ID and request requires a POST method.
<div style="position: absolute; top: 610px; left: 20px; width: 300px; height:100px; background-color: azure; border:dotted; border-width:medium">
Like A Message
<br />
Message Id <input type="text" id="txtmessageid" value="507867284" style="width: 250px; height: 20px;" />
<br />
<input type="button" onclick="likeMessage()" value="Like a Message on Yammer" />
<br />
</div>
function likeMessage() {
var messageid = document.getElementById('txtmessageid').value;
likeaMessage(messageid);
}
Note The likemessage function gets the message ID from the textbox and calls likeaMessage, defined in YammerCore.js, by passing the message ID.
function likeaMessage(messageid) {
var endpoint = "https://www.yammer.com/api/v1/messages/liked_by/current.json?message_id=[:id]".replace('[:id]', messageid)
yam.platform.request({
url: endpoint,
data:'',
method: "POST",
success: function (msg) {
console.log("Message liked Successfully");
},
error: function (msg) {
console.log("Message Posting Error: " + msg.statusText);
}
});
}
This code snippet first forms the endpoint for invoking the “like a message” API. The endpoint is https://www.yammer.com/api/v1/messages/liked_by/current.json?message_id=[:id], first replace the [:id] with the message ID of the message you would like to mark as liked. In this example, message_id is passed from customActionTarget.aspx using an input text box. The next code is the standard yam.platform.request call done by passing the URL (the endpoint we form in the first line of the function, data as empty string, method:POST, and callback functions to handle the success and failure scenarios.
Messages Management: Unlike a Liked Message
The Yammer JavaScript SDK provides following REST API, which is the same one we saw in the previous section, “Like a Message”.
https://www.yammer.com/api/v1/messages/liked_by/current.json?message_id=[:id]
Where the ID represents the target message ID and request requires a DELETE method.
<div style="position: absolute; top: 810px; left: 20px; width: 300px; height:80px; background-color: azure; border:dotted; border-width:medium">
<input type="button" onclick="UnlikeMessage()" value="Unlike a Message on Yammer" />
<br />
</div>
function UnlikeMessage() {
var messageid = document.getElementById('txtmessageid').value;
UnlikeaMessage(messageid);
}
function UnlikeaMessage(messageid) {
var endpoint = "https://www.yammer.com/api/v1/messages/liked_by/current.json?message_id=[:id]".replace('[:id]', messageid)
yam.platform.request({
url: endpoint,
data:'',
method: "DELETE",
success: function (msg) {
console.log("Message was unliked Successfully");
},
error: function (msg) {
console.log("Message Posting Error: " + msg.statusText);
}
});
}
This code snippet first forms the endpoint for invoking the “unlike a message” API. The endpoint is https://www.yammer.com/api/v1/messages/liked_by/current.json?message_id=[:id], so we need to replace the [:id] with the message ID of the message you would like to mark as unliked. In this example, the message_id is passed from customActionTarget.aspx using an input textbox. The next code is the standard yam.platform.request call created by passing the URL (the endpoint we form in the first line of the function, data as empty string, method :DELETE and call back functions to handle the success and failure scenarios.
Run the SharePoint-Hosted App
You have added all the necessary code for the SharePoint-hosted app, so you can now run the application and see the integration of the app with Yammer using JavaScript SDK in action.
Figure 7-4. Deploy the SharePoint-hosted app using Visual Studio
Figure 7-5. Deployed SharePoint-hosted app on the SharePoint Online Dev site
Figure 7-6. SharePoint-hosted app’s default page, CustomActionTarget.aspx
Figure 7-7. Yammer app’s JavaScript Origins section
Figure 7-8. Yammer’s login window, which is initiated by clicking on the “Log In with Yammer” button
Figure 7-9. After successful login, the page displays the markup to test other features of the JavaScript SDK
So, in this exercise, we extended the SPDS University SharePoint-hosted app to integrate Yammer functionalities by using the Yammer JavaScript SDK.
In a similar manner, you can use the Yammer JavaScript SDK in your business application to provide authentication using Yammer and then read and write data to Yammer.
Summary
By now you are familiar with the Yammer SDKs released by Yammer. First, you learned about the Yammer JavaScript SDK, the authentication functions, and the other functions available in the SDK. You also learned to integrate a JavaScript-enabled application with Yammer. In the next chapter, you will learn how to integrate a Windows phone app with Yammer using the Windows Phone SDK.