Namespace: Interface

Cocoon.Social. Interface

This interface provides an abstraction API for all the Social Services, this is an interface and never should be call directly. Each Social service has it's own official API but can also be used within this API interface. In order to use this interface you should call the method getSocialInterface(); that is available in the following classes:

Example

// You can use one of these 3 services with the same API.
// In this example we'll use Facebook
var service = Cocoon.Social.Facebook;
//var service = Cocoon.Social.GameCenter;
//var service = Cocoon.Social.GooglePlayGames;

// Each service has it's own init method,
// Refer to each service API to know how to initialize it.
service.init({
    appId: "XXXXXXXXXXXXXXXXXXXXX",
    channelUrl: "//connect.facebook.net/en_US/all.js"
});

var socialService = service.getSocialInterface();

function loginFacebook() {
  if (!socialService.isLoggedIn()) {
      socialService.login(function(loggedIn, error) {
          if (error) {
              console.error("login error: " + error.message);
          }
          else if (loggedIn) {
              var message = new Cocoon.Social.Message(
                  "Hello there! Are you a HTML5 game developer? Come and check out Cocoon.io!",
                  "https://cocoon.io/assets2/images/layout/cordovainside.png",
                  "http://cocoon.io",
                  "Ludei & Cocoon.io",
                  "We love HTML5 games!");

              socialService.publishMessageWithDialog(message, function(error) {
                  if (error) {
                      console.error("Error publishing message: " + error.message);
                  }
              });
           }
           else {
              console.log("login cancelled");
           }
      });
  }
}
loginFacebook();

Methods

<static> addScore(score, callback, params)

Adds a score to the current user core for a specific leaderboard

Parameters:
Name Type Argument Description
score number

The score to submit

callback function <optional>

The callback function. Response params: error.

params Cocoon.Social.ScoreParams <optional>

The params to submit the score. If no params are specified, the currently logged in user and the default leaderboard are assumed.

<static> getLoggedInUser()

Returns the information of the currently logged in user.

Returns:

<static> hasPublishPermissions(callback)

Checks if the current logged in user has publish permissions.

Parameters:
Name Type Description
callback

The callback function. It receives the following parameters: permissions granted and error

<static> isLoggedIn() → {boolean}

Checks if the user is logged in.

Returns:

true if the user is still logged in, false otherwise.

Type
boolean

<static> login(callback)

Authenticates the user.

Parameters:
Name Type Description
callback function

The callback function. Response params: loggedIn(boolean) and error

Example
var fb = Cocoon.Social.Facebook;

fb.init({
    appId: "XXXXXXXXXXXXXXXXXXXXX",
    channelUrl: "//connect.facebook.net/en_US/all.js"
});

var socialService = fb.getSocialInterface();
var loggedIn = socialService.isLoggedIn();

function loginFacebook() {
  if (!socialService.isLoggedIn()) {
      socialService.login(function(loggedIn, error) {
           if (error) {
              console.error("login error: " + error.message);
           }
           else if (loggedIn) {
              console.log("login succeeded");
           }
           else {
              console.log("login cancelled");
           }
      });
  }
}
loginFacebook();

<static> logout(callback)

Logs the user out of your application.

Parameters:
Name Type Argument Description
callback function <optional>

The callback function. Response params: error.

Example
var fb = Cocoon.Social.Facebook;

fb.init({
    appId: "XXXXXXXXXXXXXXXXXXXXX",
    channelUrl: "//connect.facebook.net/en_US/all.js"
});

var socialService = fb.getSocialInterface();

socialService.logout(function(error){

});

<static> publishMessage(message, callback)

Shares a message without the intervention of the user. This action might require publish permissions. If the user has not publish permissions they are automatically requested.

Parameters:
Name Type Argument Description
message Cocoon.Social.Message

A object representing the information to be published.

callback function <optional>

The callback function. It receives the following parameters: error.

Example
var fb = Cocoon.Social.Facebook;

fb.init({
    appId: "XXXXXXXXXXXXXXXXXXXXX",
    channelUrl: "//connect.facebook.net/en_US/all.js"
});

var socialService = fb.getSocialInterface();
var loggedIn = socialService.isLoggedIn();

if (loggedIn) {
    var message = new Cocoon.Social.Message(
    "Hello from the CocoonJS Launcher App! Are you a HTML5 game developer? Come and check out CocoonJS!",
    "https://cocoonjsadmin.ludei.com/static/images/cocoon_logo.png",
    "http://ludei.com",
    "Ludei & CocoonJS",
    "We love HTML5 games!");

    socialService.publishMessage(message, function(error) {
         if (error) {
             console.error("Error publishing message: " + error.message);
         }
     });
}

<static> publishMessageWithDialog(message, callback)

Presents a native/web dialog that allows the user to share a message.

Parameters:
Name Type Description
message Cocoon.Social.Message

A object representing the information to be published

callback function

The callback function. It receives the following parameters: error

Example
var fb = Cocoon.Social.Facebook;

fb.init({
    appId: "XXXXXXXXXXXXXXXXXXXXX",
    channelUrl: "//connect.facebook.net/en_US/all.js"
});

var socialService = fb.getSocialInterface();
var loggedIn = socialService.isLoggedIn();

if (loggedIn) {
    var message = new Cocoon.Social.Message(
    "Hello from the CocoonJS Launcher App! Are you a HTML5 game developer? Come and check out CocoonJS!",
    "https://cocoonjsadmin.ludei.com/static/images/cocoon_logo.png",
    "http://ludei.com",
    "Ludei & CocoonJS",
    "We love HTML5 games!");

    socialService.publishMessageWithDialog(message, function(error) {
         if (error) {
             console.error("Error publishing message: " + error.message);
         }
    });
}

<static> requestAchievements(callback, userId)

Retrieves the achievements earned by a user.

Parameters:
Name Type Argument Description
callback function

The callback function. It receives the following parameters:

userId string <optional>

The id of the user to retrieve the information from. If no userID is specified, the currently logged in user is assumed.

<static> requestAllAchievements(callback)

Retrieves all the achievements of the application.

Parameters:
Name Type Description
callback function

The callback function. It receives the following parameters:

<static> requestFriends(callback, userID)

Retrieves user friends for a specific user ID.

Parameters:
Name Type Description
callback function

The callback function. It receives the following parameters:

userID string

The id of the user to retrieve the information from. If no userID is specified, the currently logged in user is assumed.

Example
var fb = Cocoon.Social.Facebook;

fb.init({
    appId: "XXXXXXXXXXXXXXXXXXXXX",
    channelUrl: "//connect.facebook.net/en_US/all.js"
});

var socialService = fb.getSocialInterface();

var loggedIn = socialService.isLoggedIn();

if (loggedIn) {
  socialService.requestFriends(function(friends, error) {
       if (error) {
           console.error("requestFriends error: " + error.message);
      }
      else {
         console.log("You have " + friends.length + " friends.");
      }
  });
}

<static> requestPublishPermissions(callback)

Requests publish permissions for the current logged in user.

Parameters:
Name Type Description
callback

The callback function. It receives the following parameters: granted and error

<static> requestScore(callback, params)

Retrieves the score for a user from a specific leaderboard

Parameters:
Name Type Argument Description
callback function

The callback function. It receives the following parameters:

params Cocoon.Social.ScoreParams <optional>

The params to retrieve the score. If no params are specified, the currently logged in user and the default leaderboard are assumed.

<static> requestUser(callback, userID)

Retrieves user information for a specific user ID.

Parameters:
Name Type Description
callback function

The callback function. It receives the following parameters:

userID string

The id of the user to retrieve the information from. If no userID is specified, the currently logged in user is assumed.

Example
var fb = Cocoon.Social.Facebook;

fb.init({
    appId: "XXXXXXXXXXXXXXXXXXXXX",
    channelUrl: "//connect.facebook.net/en_US/all.js"
});

var socialService = fb.getSocialInterface();
var loggedIn = socialService.isLoggedIn();

if (loggedIn) {
  socialService.requestUser(function(user, error) {
       if (error) {
           console.error("requestUser error: " + error.message);
      }
      else {
          console.log(user.userName);
       }
  }, userID);
}

<static> requestUserImage(callback, userID, imageSize)

Requests to retrieve the profile image of a user.

Parameters:
Name Type Description
callback function

The callback function. It receives the following parameters:

  • ImageURL.
  • Error.
userID string

The id of the user to get the image for. If no userID is specified, the currently logged user is used.

imageSize Cocoon.Social.ImageSize

The desired size of the image. Default value: SMALL.

<static> resetAchievements(callback)

Resets all the achievements of the current logged in user

Parameters:
Name Type Argument Description
callback function <optional>

The callback function. Response params: error.

Example
var fb = Cocoon.Social.Facebook;

fb.init({
    appId: "XXXXXXXXXXXXXXXXXXXXX",
    channelUrl: "//connect.facebook.net/en_US/all.js"
});

var socialService = fb.getSocialInterface();

socialService.resetAchievements(function(error){
    if (error)
        console.error("resetAchievements error: " + error.message);
});

<static> setAchievementsMap()

Set the map for using custom achievement IDs. The map must be a customID to realID map (accessing map.customID must return the real achievement ID). Whenever this map is enabled users are able to submit achievements with the real achievement ID or with the custom one.

<static> setTemplates(leaderboardsTemplate, achievementsTemplate)

Provides some templates to be used in the leaderboards and achievements views Some social services (like Facebook) don't have a native view to show achievements or leaderboards views, and use html templates instead.

Parameters:
Name Type Description
leaderboardsTemplate string

Relative path to the leaderboards template.

achievementsTemplate string

Relative path to the achievements template.

<static> showAchievements(callback)

Shows a modal achievements view using a platform dependant view.

Parameters:
Name Type Argument Description
callback function <optional>

The callback function invoked when the modal achievements view is closed by the user. Response params: error.

Example
var fb = Cocoon.Social.Facebook;

fb.init({
    appId: "XXXXXXXXXXXXXXXXXXXXX",
    channelUrl: "//connect.facebook.net/en_US/all.js"
});

var socialService = fb.getSocialInterface();
var loggedIn = socialService.isLoggedIn();

socialService.showAchievements(function(error){
    if (error)
        console.error("showAchievements error: " + error.message);
});

<static> showLeaderboard(params, callback)

Shows a modal leaderboard view using a platform dependant view.

Parameters:
Name Type Argument Description
params Cocoon.Social.ScoreParams <optional>

The params to choose the leaderboard and other settings. If no params are specified the default leaderboard id and settings will be assumed.

callback function <optional>

The callback function invoked when the modal leaderboard view is closed by the user. Response params: error.

Example
var fb = Cocoon.Social.Facebook;

fb.init({
    appId: "XXXXXXXXXXXXXXXXXXXXX",
    channelUrl: "//connect.facebook.net/en_US/all.js"
});

var socialService = fb.getSocialInterface();
var loggedIn = socialService.isLoggedIn();

socialService.showLeaderboard(function(error){
    if (error)
        console.error("showLeaderbord error: " + error.message);
});

<static> submitAchievement(achievementID, callback)

Submits the achievement for the current logged In user

Parameters:
Name Type Description
achievementID

The achievement ID to submit

callback

[callback] The callback function. Response params: error.

Example
var fb = Cocoon.Social.Facebook;

fb.init({
    appId: "XXXXXXXXXXXXXXXXXXXXX",
    channelUrl: "//connect.facebook.net/en_US/all.js"
});

var socialService = fb.getSocialInterface();

socialService.submitAchievement( achievementID, function(error){
    if (error)
        console.error("submitAchievement error: " + error.message);
});

<static> submitScore(score, callback, params)

Submits the score for a user to a specific leaderboard

Parameters:
Name Type Argument Description
score number

The score to submit

callback function <optional>

The callback function. Response params: error.

params Cocoon.Social.ScoreParams <optional>

The params to submit the score. If no params are specified, the currently logged in user and the default leaderboard are assumed.

Events

On loginStatusChanged

Triggered when the user's login status has changed.

Example
socialAPI.on("loginStatusChanged", function(loggedIn){
   console.log("User logged in?: " + loggedIn);
});
Atomic Plugins - JavaScript Documentation by Ludei, DocStrap Copyright © 2012-2013
The contributors to the JSDoc3 and DocStrap projects.