{"_id":"54738f761a20c70800e189bc","version":{"_id":"545137a814af501a00b50cfc","project":"545137a814af501a00b50cf9","__v":11,"createdAt":"2014-10-29T18:53:28.525Z","releaseDate":"2014-10-29T18:53:28.525Z","categories":["545137a814af501a00b50cfd","545138eaa66f020800dbab4a","546b9072b47b5d1400109edf","546b9082b47b5d1400109ee0","546b9088b47b5d1400109ee1","546b909462515a14007ebc43","546b90a0b47b5d1400109ee2","546ced235884600e007a92f6","5481008eea7fd40b00cd7c2b","573b9d83ee2b3b220042291f","57be1efa15efc70e006a5f99"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"__v":13,"category":{"_id":"546b90a0b47b5d1400109ee2","project":"545137a814af501a00b50cf9","pages":["54738f761a20c70800e189bc","54738f7f1a20c70800e189be","54738f91007eb108007e041d","54738fa71a20c70800e189c1","54738fbd007eb108007e041f","54739056007eb108007e0421"],"version":"545137a814af501a00b50cfc","__v":6,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2014-11-18T18:32:00.749Z","from_sync":false,"order":6,"slug":"sdks","title":"SDKs"},"project":"545137a814af501a00b50cf9","user":"5433099f9a2b451a00ad4531","parentDoc":null,"updates":["54d941544c49f40d00dff947","54d942963268702d007d9441","5719872a6346850e0083416f","59777dd41a2038001fc9bd32"],"next":{"pages":[],"description":""},"createdAt":"2014-11-24T20:05:10.950Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"basic_auth":false,"results":{"codes":[]},"try":true,"settings":"","auth":"never","params":[],"url":""},"isReference":false,"order":0,"body":"Use the Yammer SDKs to authenticate users with Yammer and access Yammer APIs in the technology of your choice. JavaScript, Ruby, Python, iOS, Windows Phone 8, and .NET SDKs are currently available.\n\n\n**JavaScript SDK**\n\nThe JavaScript SDK enables you to include Yammer authentication, features and data into your application on the client side. To start using the SDK, first, make sure that all domains on which you intend to use the SDK have been registered in the **javascript origins section** of your app's configuration::\n[block:image]\n{\n  \"images\": [\n    {\n      \"caption\": \"The `Javascript Origins box` can be found at the bottom of app configuration page\",\n      \"image\": [\n        \"https://files.readme.io/6vdQtfWQSGTFzw29U8gc_Screen%20Shot%202015-02-05%20at%2010.54.48%20AM.png\",\n        \"Screen Shot 2015-02-05 at 10.54.48 AM.png\",\n        \"1412\",\n        \"1238\",\n        \"#1d4d3b\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n**NOTE**: If the SDK is hosted on a domain that has not been registered, your app will not work\n**NOTE**: Under normal circumstances, users will have to create a Yammer session before using the JS SDK in scenarios like apps integrated on intranet pages.  If you’re able to implement both server and client side scripting and pull the current user’s email address, you can use [a guide to preauthorize a Yammer session](https://blogs.technet.microsoft.com/askyammer/2016/11/04/preauthorizing-the-yammer-js-sdk/) so that apps utilizing the JS SDK will be as seamless as possible.\n\nNext, include the following snippet in your HTML:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<script type=\\\"text/javascript\\\" data-app-id=\\\"YOUR-APP-CLIENT-ID\\\" src=\\\"https://c64.assets-yammer.com/assets/platform_js_sdk.js\\\"></script>\\n\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\nAs of April 7, 2014 this version of the JS SDK has been updated with new security features. The documentation below reflects these changes.\n\n**Authentication**\n\n\"Login with Yammer” button\n\nThe first step is to authenticate your app to connect to Yammer with the user’s Yammer credentials. The simplest way to do this is to use the “Login with Yammer” button:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<span id=\\\"yammer-login\\\"></span>\\n<script>\\n  yam.connect.loginButton('#yammer-login', function (resp) {\\n    if (resp.authResponse) {\\n      document.getElementById('yammer-login').innerHTML = 'Welcome to Yammer!';\\n    }\\n  });\\n</script>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\nYou pass a selector and a callback to yam.connect.loginButton. The element selected will become a standard “Login with Yammer” button. When clicked it will initiate the OAuth workflow and after the user approves or denies your application the callback will fire. To verify that the user did in fact login and approve your application you’ll need to check the resp.authResponse property. Once verified, make calls to the Yammer REST API using the functions of the JavaScript API below.\n\nNote, if the login was successful the response object will have a session object which includes the OAuth token for the current user in their currently selected Yammer network.\n\n**Login function** \n\nGetLoginStatus\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"yam.platform.getLoginStatus(callback, [forceRefresh])\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nDetermines whether the current user is logged in to Yammer and connected to your application. The first time the method is called, it will query the Yammer API and when this responds callback will be invoked with the server response as the only argument. Calling the method subsequently will return the cached response unless forceRefresh is set to true.\n\nSubsequent calls to yam.platform.request will automatically use the token returned by this call.\n\nThe flow below lets you do the authentication using the yam.platform.login function, if you do not want to use the “Login with Yammer” button.\n\nThe JavaScript SDK allows developers to share the logged in user state between yammer.com and their site. A Yammer user remains logged into the 3rd party site. To start, find out the authentication status of the user with the getLoginStatus function.\n\nThe code sample below answers the question “who is the current user?” by saying it’s either someone you know (and prints the user’s information to the console) or someone you don’t know, either because they aren’t currently logged into Yammer or they haven’t authorized your app yet.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"yam.getLoginStatus(\\n  function(response) {\\n    if (response.authResponse) {\\n      alert(\\\"logged in\\\");\\n        console.dir(response); //print user information to the console\\n      }\\n    else {\\n      //authResponse = false if the user is not logged in, or is logged in but hasn't authorized your app yet\\n      alert(\\\"logged out\\\");\\n    }\\n  }\\n);\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nOnce the page has checked the user’s status, the user may need to be prompted to login and authorize your app against their Yammer user account. The sample code below shows an example of how to check the user’s status and react by prompting the user to log in and authorize your app, if necessary.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"yam.platform.login([opts], [callback])\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nTriggers a login dialog popup. When the login flow is completed the *callback *will be invoked with the access token as the only argument.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"yam.getLoginStatus(\\n  function(response) {\\n    if (response.authResponse) {\\n      console.log(\\\"logged in\\\");\\n      console.dir(response); //print user information to the console\\n    }\\n    else {\\n      yam.platform.login(function (response) { //prompt user to login and authorize your app, as necessary\\n        if (response.authResponse) {\\n          console.dir(response); //print user information to the console\\n        }\\n      });\\n    }\\n  }\\n);\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nThe dialog is located at: \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"https://www.yammer.com/dialog/oauth\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\nCalling the yam.platform.login method for a user that is not logged in or hasn’t authenticated your app opens a popup and therefore should only be called on a user event to prevent the browser from blocking it. Also, be sure to call yam.platform.login inside a function(response) within getLoginStatus. Calling getLoginStatus lazy-loads components that you need to use yam.login and waiting on the response will ensure that yam.login functions correctly.\n\nThe callback function is invoked when the popup is closed. If the login was successful the response object passed to the callback function will have a session object which includes the OAuth token for the current user in their Yammer network.\n\n\n**Making Yammer API Requests** \n\nYou can make calls directly to the Yammer REST API directly from the user’s browser.\n\nWhen calling the REST API through the JS SDK, you will need to use the api.yammer.com instead of www.yammer.com hostname. You can also make calls to Yammer REST endpoints without any hostname. To do this, only call the resource followed by the format you want returned. Some examples for the Messages endpoint (http://www.yammer.com/api/v1/messages.json) could be to call ‘messages.json’.\n\nThe call below makes requests to the Yammer API using the bearer token provided through yam.platform.setAuthToken, retrieved for the users current session via\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"yam.platform.getLoginStatus\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nor returned by the login flow triggered by yam.platform.login. The options argument mirrors jQuery Ajax, with the addition that if url is relative it will be automatically qualified to the API domain.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"yam.platform.request(options)\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n*Example:*  \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"yam.getLoginStatus(\\n  function(response) {\\n    if (response.authResponse) {\\n      console.log(\\\"logged in\\\");\\n      yam.platform.request({\\n        url: \\\"users.json\\\",     //this is one of many REST endpoints that are available\\n        method: \\\"GET\\\",\\n        data: {    //use the data object literal to specify parameters, as documented in the REST API section of this developer site\\n          \\\"letter\\\": \\\"a\\\",\\n          \\\"page\\\": \\\"2\\\",\\n        },\\n        success: function (user) { //print message response information to the console\\n          alert(\\\"The request was successful.\\\");\\n          console.dir(user);\\n        },\\n        error: function (user) {\\n          alert(\\\"There was an error with the request.\\\");\\n        }\\n      });\\n    }\\n    else {\\n      alert(\\\"not logged in\\\")\\n    }\\n  }\\n);\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nWe also support the rest of the jQuery.ajax() standard attributes including type in place of method.\n\n\n**Logout**\n\nJust like logging in is tied to yammer.com, so is logging out. Again, be sure to check the user’s login status prior to attempting to log them out so all of the components that yam.logout needs are loaded.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"yam.platform.logout([callback])\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nLogs the user out based on their current bearer token. The callback will be invoked with a single boolean argument to indicate whether logout succeeded or failed.\n\n*Example:* \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \" yam.getLoginStatus(\\n    function(response) {\\n      if(response.authResponse) {\\n        yam.platform.logout(function (response) {\\n          alert(\\\"user was logged out\\\");\\n        })\\n      }\\n    }\\n  );\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]","excerpt":"","slug":"js-sdk","type":"basic","title":"JavaScript SDK"}
Use the Yammer SDKs to authenticate users with Yammer and access Yammer APIs in the technology of your choice. JavaScript, Ruby, Python, iOS, Windows Phone 8, and .NET SDKs are currently available. **JavaScript SDK** The JavaScript SDK enables you to include Yammer authentication, features and data into your application on the client side. To start using the SDK, first, make sure that all domains on which you intend to use the SDK have been registered in the **javascript origins section** of your app's configuration:: [block:image] { "images": [ { "caption": "The `Javascript Origins box` can be found at the bottom of app configuration page", "image": [ "https://files.readme.io/6vdQtfWQSGTFzw29U8gc_Screen%20Shot%202015-02-05%20at%2010.54.48%20AM.png", "Screen Shot 2015-02-05 at 10.54.48 AM.png", "1412", "1238", "#1d4d3b", "" ] } ] } [/block] **NOTE**: If the SDK is hosted on a domain that has not been registered, your app will not work **NOTE**: Under normal circumstances, users will have to create a Yammer session before using the JS SDK in scenarios like apps integrated on intranet pages. If you’re able to implement both server and client side scripting and pull the current user’s email address, you can use [a guide to preauthorize a Yammer session](https://blogs.technet.microsoft.com/askyammer/2016/11/04/preauthorizing-the-yammer-js-sdk/) so that apps utilizing the JS SDK will be as seamless as possible. Next, include the following snippet in your HTML: [block:code] { "codes": [ { "code": "<script type=\"text/javascript\" data-app-id=\"YOUR-APP-CLIENT-ID\" src=\"https://c64.assets-yammer.com/assets/platform_js_sdk.js\"></script>\n", "language": "html" } ] } [/block] As of April 7, 2014 this version of the JS SDK has been updated with new security features. The documentation below reflects these changes. **Authentication** "Login with Yammer” button The first step is to authenticate your app to connect to Yammer with the user’s Yammer credentials. The simplest way to do this is to use the “Login with Yammer” button: [block:code] { "codes": [ { "code": "<span id=\"yammer-login\"></span>\n<script>\n yam.connect.loginButton('#yammer-login', function (resp) {\n if (resp.authResponse) {\n document.getElementById('yammer-login').innerHTML = 'Welcome to Yammer!';\n }\n });\n</script>", "language": "html" } ] } [/block] You pass a selector and a callback to yam.connect.loginButton. The element selected will become a standard “Login with Yammer” button. When clicked it will initiate the OAuth workflow and after the user approves or denies your application the callback will fire. To verify that the user did in fact login and approve your application you’ll need to check the resp.authResponse property. Once verified, make calls to the Yammer REST API using the functions of the JavaScript API below. Note, if the login was successful the response object will have a session object which includes the OAuth token for the current user in their currently selected Yammer network. **Login function** GetLoginStatus [block:code] { "codes": [ { "code": "yam.platform.getLoginStatus(callback, [forceRefresh])", "language": "javascript" } ] } [/block] Determines whether the current user is logged in to Yammer and connected to your application. The first time the method is called, it will query the Yammer API and when this responds callback will be invoked with the server response as the only argument. Calling the method subsequently will return the cached response unless forceRefresh is set to true. Subsequent calls to yam.platform.request will automatically use the token returned by this call. The flow below lets you do the authentication using the yam.platform.login function, if you do not want to use the “Login with Yammer” button. The JavaScript SDK allows developers to share the logged in user state between yammer.com and their site. A Yammer user remains logged into the 3rd party site. To start, find out the authentication status of the user with the getLoginStatus function. The code sample below answers the question “who is the current user?” by saying it’s either someone you know (and prints the user’s information to the console) or someone you don’t know, either because they aren’t currently logged into Yammer or they haven’t authorized your app yet. [block:code] { "codes": [ { "code": "yam.getLoginStatus(\n function(response) {\n if (response.authResponse) {\n alert(\"logged in\");\n console.dir(response); //print user information to the console\n }\n else {\n //authResponse = false if the user is not logged in, or is logged in but hasn't authorized your app yet\n alert(\"logged out\");\n }\n }\n);", "language": "javascript" } ] } [/block] Once the page has checked the user’s status, the user may need to be prompted to login and authorize your app against their Yammer user account. The sample code below shows an example of how to check the user’s status and react by prompting the user to log in and authorize your app, if necessary. [block:code] { "codes": [ { "code": "yam.platform.login([opts], [callback])", "language": "javascript" } ] } [/block] Triggers a login dialog popup. When the login flow is completed the *callback *will be invoked with the access token as the only argument. [block:code] { "codes": [ { "code": "yam.getLoginStatus(\n function(response) {\n if (response.authResponse) {\n console.log(\"logged in\");\n console.dir(response); //print user information to the console\n }\n else {\n yam.platform.login(function (response) { //prompt user to login and authorize your app, as necessary\n if (response.authResponse) {\n console.dir(response); //print user information to the console\n }\n });\n }\n }\n);", "language": "javascript" } ] } [/block] The dialog is located at: [block:code] { "codes": [ { "code": "https://www.yammer.com/dialog/oauth", "language": "text" } ] } [/block] Calling the yam.platform.login method for a user that is not logged in or hasn’t authenticated your app opens a popup and therefore should only be called on a user event to prevent the browser from blocking it. Also, be sure to call yam.platform.login inside a function(response) within getLoginStatus. Calling getLoginStatus lazy-loads components that you need to use yam.login and waiting on the response will ensure that yam.login functions correctly. The callback function is invoked when the popup is closed. If the login was successful the response object passed to the callback function will have a session object which includes the OAuth token for the current user in their Yammer network. **Making Yammer API Requests** You can make calls directly to the Yammer REST API directly from the user’s browser. When calling the REST API through the JS SDK, you will need to use the api.yammer.com instead of www.yammer.com hostname. You can also make calls to Yammer REST endpoints without any hostname. To do this, only call the resource followed by the format you want returned. Some examples for the Messages endpoint (http://www.yammer.com/api/v1/messages.json) could be to call ‘messages.json’. The call below makes requests to the Yammer API using the bearer token provided through yam.platform.setAuthToken, retrieved for the users current session via [block:code] { "codes": [ { "code": "yam.platform.getLoginStatus", "language": "javascript" } ] } [/block] or returned by the login flow triggered by yam.platform.login. The options argument mirrors jQuery Ajax, with the addition that if url is relative it will be automatically qualified to the API domain. [block:code] { "codes": [ { "code": "yam.platform.request(options)", "language": "javascript" } ] } [/block] *Example:* [block:code] { "codes": [ { "code": "yam.getLoginStatus(\n function(response) {\n if (response.authResponse) {\n console.log(\"logged in\");\n yam.platform.request({\n url: \"users.json\", //this is one of many REST endpoints that are available\n method: \"GET\",\n data: { //use the data object literal to specify parameters, as documented in the REST API section of this developer site\n \"letter\": \"a\",\n \"page\": \"2\",\n },\n success: function (user) { //print message response information to the console\n alert(\"The request was successful.\");\n console.dir(user);\n },\n error: function (user) {\n alert(\"There was an error with the request.\");\n }\n });\n }\n else {\n alert(\"not logged in\")\n }\n }\n);", "language": "javascript" } ] } [/block] We also support the rest of the jQuery.ajax() standard attributes including type in place of method. **Logout** Just like logging in is tied to yammer.com, so is logging out. Again, be sure to check the user’s login status prior to attempting to log them out so all of the components that yam.logout needs are loaded. [block:code] { "codes": [ { "code": "yam.platform.logout([callback])", "language": "javascript" } ] } [/block] Logs the user out based on their current bearer token. The callback will be invoked with a single boolean argument to indicate whether logout succeeded or failed. *Example:* [block:code] { "codes": [ { "code": " yam.getLoginStatus(\n function(response) {\n if(response.authResponse) {\n yam.platform.logout(function (response) {\n alert(\"user was logged out\");\n })\n }\n }\n );", "language": "javascript" } ] } [/block]