">mixi Developer Center (mDC)

mixi Apps

mixi Apps (English) » Technical Specification » PC » User Profile Information/Friend Information

User Profile Information/Friend Information

The key feature of the mixi App lies in mixi’s social graph, making use of profile information and Friend’s information. OpenSocial prescribes features for accessing profile information and/or Friend information from applications. Learning how to handle the profile information and Friend information is the first step for understanding mixi Apps development.

friends

mixi App enables a user to handle the following user profile information and to obtain a list of Friends. These processes are described by the OpenSocial JavaScript API as Person & Friends API.

  • ID
  • Nickname
  • Profile photo
  • Profile URL
  • Address (prefecture only)
  • Age
  • Birth date
  • Gender
  • Blood type

mixi App is a social application embedded and executed on mixi’s page. Therefore, the way of developing social application, especially in handling the user is unique to other application.

Owners and Viewers

A user can find new or interesting mixi Apps through the application search page and/or an activity feed and invitation from Friends. When the user finds an interesting application, she/he must install the application. The installed application is displayed in the list of applications on the user’s home page, allowing her/him to access the application at anytime.

This means that mixi App employs the concept of “owner.” For example, assuming persons A and B have installed a fortune-telling application, each application is deemed as “A’s fortune-telling application” and “B’s fortune-telling application.” In this example, person A and person B are called “owners” in OpenSocial.

Person A is able to see the fortune-telling application in A’s profile page or the result of the fortune-telling application may feed on mixi’s homepage.. Now, let us assume that another user C visits person A’s profile page and sees the fortune-telling application. In this case, the owner of the fortune-telling application is person A, but it is person C who operates the application.

In this case, person C is called a “Viewer” in OpenSocial. When the person A runs the application installed on her/his own profile page, that person A becomes both the Owner and Viewer of the application.

owner_viewer

A developers of a mixi App should design and implement the application taking “who runs the application” and “whose application is run” into consideration. In addition to the distinction between the Owner and the Viewer, the developer should make sure where or in what page the application is executed,. For example, if a user executes mixi App on the Canvas view, the user of the application must be the viewer so that only necessary content or functionality should be available to the viewer. Meanwhile, if a mixi App is run in the Profile view, the user should be the Owner and any resources including personal information of the user are available.

When accessing profile information and/or Friend information, a developer should recognize the difference between the Owner and Viewer properly. Depending on the difference, accessibility and/or availability of information can be controlled.

Acquisition of Profile Information

The most characteristic and fundamental information in terms of the mixi App is a user profile information. Based on the profile information, the mixi App can be customized and provided for each user. You can acquire profiles of the Owner, Viewer and other users through some JavaScript APIs prescribed by OpenSocial from mixi servers.

Request of User Profile Information

Example code for acquiring profile information of users (viewers) of mixi Apps is shown in the list below.

var req = opensocial.newDataRequest();
req.add(req.newFetchPersonRequest(opensocial.IdSpec.PersonId.VIEWER), "viewer");
req.send(function(data) {
    if (data.hadError()) {
        var msg = data.getErrorMessage();
        // エラー発生時の処理
    } else {
        // 取得結果に対する処理
    }
});

The OpenSocial JavaScript APIs are stated to generate various request objects, add them to opensocial.DataRequest objects, and process them at the same time when requesting a server to acquire and/or update information.

First of all, a DataRequest object for sending a request is created with newDataRequest(). .Secondly,, newFetchPersonRequest() generated by the foregoing DataRequest object enables the developer to create a new object to request profile information of a user. Then, add() enables the developer to add another request object to the DataRequest object.

The first parameter of the newFetchPersonRequest() identifies a user from the followings:

  • Viewer (user operating the application) – opensocial.IdSpec.PersonId.VIEWER
  • Owner (owner of the application) – opensocial.IdSpec.PersonId.OWNER
  • Specific user – ID of the user whose profile is to be acquired

Basically, profile information can be acquired by specifying a user ID.Profile information of the Viewer and/or Owner,can be gained by parameter stated in IdSpec.PersonId class.

When using the add() function of the DataRequest class, the developer specify the request object generated by the newFetchPersonRequest() or other functions in the first parameter and . a key character string to be used to retrieve the result of the request in the second parameter.

After adding the request object, a request for the profile information is sent from a mixi App to a mixi server by calling the send(). When the result is received, the callback function is called specified in the parameter of the send() . The developer should notice that processing a request to the server and receiving the result are asynchronous.

The hadError() in the parameter of the callback function enables the developer to check an error when it is occurred. In the case the error has occurred, the developer should handle the error properly by examining the error through the getErrorCode() or getErrorMessage() This error handling process must be implemented for the stable operation of mixi Apps.

Retrieving the Profile Information from the Acquired Result

Following is sample code for retrieving the profile information from mixi server.

req.send(function(data) {
    if (!data.hadError()) {
        var item = data.get("viewer");
        if (item.hadError()) {
          var code = item.getErrorCode();
          // エラー処理
        } else {
          var viewer = item.getData();
          var id = viewer.getId();
          var nickname = viewer.getDisplayName();
          var thumbnailUrl = viewer.getField(opensocial.Person.Field.THUMBNAIL_URL);
          // プロフィール情報を使った処理
        }
    }
});

An opensocial.DataResponse class object is used as the parameter of the callback function. By get() of the DataResponse object the developer is able to retrieve each object with the results generated by a series of the request object. At this point, the key character string specified with the add().is used.

The object obtained from the get() is an opensocial.ResponseItem class object. This object is used to hold the result from each request object. This ResponseItem object has functions related to error handling, including the hadError() or getErrorCode() . The aforementioned DataResponse object handles overall error information from multiple requests and the ResponseItem object handles specific error information from a single request.

By the getData() in the RepsonseItem object, the developer is able to retrieve from a result generated by newFetchPersonRequest() which contains the profile information of a specific user.. The result from the getData() is an opensocial.Person class object. This Person object literally holds the profile information.

ID and nickname among the profile information can be obtained from following:

  • ID – getId()
  • Nickname – getDisplayName()

In order to retrieve other profile information, the developer can specify the type of information as an parameter of this getField(),. The types are described in the opensocial.Person.Field class and mixi.PersonField class.

In the sample code above, the URL of user’s thumbnail image is acquired by specifying the opensocial.Person.Field.THUMBNAIL_URL as an parameter of the getField().

Requesting Many Profile Information Items

In the sample code, only one parameter is given for newFetchPersonRequest() . In this case, only following types of the profile information can be obtained:

  • ID – getId()
  • Nickname – getDisplayName()
  • Image in profile – getField(opensocial.Person.Field.THUMBNAIL_URL)

Because communicating all profile information might cause serious issue in terms of bandwidth usage, we apply such limitation.

In order to obtain information other than the 3 items, the developer has to specify the information s/he is interested .by opensocial.DataRequest.PeopleRequestFields.PROFILE_DETAILS.

var params = {};
params[opensocial.DataRequest.PeopleRequestFields.PROFILE_DETAILS] = [
    opensocial.Person.Field.PROFILE_URL,
    opensocial.Person.Field.ADDRESSES,
    opensocial.Person.Field.AGE,
    opensocial.Person.Field.DATE_OF_BIRTH,
    opensocial.Person.Field.GENDER,
    opensocial.Person.Field.HAS_APP,
    mixi.PersonField.BLOOD_TYPE
];
var req = opensocial.newDataRequest();
req.add(req.newFetchPersonRequest(opensocial.IdSpec.PersonId.VIEWER, params), "viewer");
req.send(function(data) {
  // プロフィール情報使った処理
});

In this sample code, PROFILE_DETAILS is used as the key to specify the items to be acquired in an array. It is possible to acquire many information items by specifying this params object in the second parameter of the newFetchPersonRequest. In the array written in the sample code all the items that a mixi App can obtain are specified. Each item specified by PROFILE_DETAILS will be acquired with the getField() in the Person object. An example of this is shown below. Note that error handling is omitted here.

req.send(function(data) {
  var viewer = data.get("viewer").getData();
  var id = viewer.getId();
  var nickname = viewer.getDisplayName();
  var thumbnailUrl = viewer.getField(opensocial.Person.Field.THUMBNAIL_URL);
  var profileUrl = viewer.getField(opensocial.Person.Field.PROFILE_URL);
  var pref = viewer.getField(opensocial.Person.Field.ADDRESSES)[0].getField(opensocial.Address.Field.UNSTRUCTURED_ADDRESS);
  var age = viewer.getField(opensocial.Person.Field.AGE);
  var birth = viewer.getField(opensocial.Person.Field.DATE_OF_BIRTH);
  var gender = viewer.getField(opensocial.Person.Field.GENDER).getKey();
  var hasApp = viewer.getField(opensocial.Person.Field.HAS_APP);
  var bloodType = viewer.getField(mixi.PersonField.BLOOD_TYPE);
  // プロフィール情報を使った処理
}

HAS_APP is an item for obtaining the information whether or not the acquired user has installed this application.

Acquisition of Friends’ Information

So far, we have introduced how to obtaine the profile information of a single user. In a mixi App specification,a function obtaining profile information of multiple Friends Is available This function,enables the developer to utilize the list of my Friends and based on the list, mixi APP can be more powerful social application.

Users and Groups

OpenSocial describes 3 applicable condtions to obtain information of a group of users:

  • USER_ID – Reference a user’s ID
  • GROUP_ID – Relationship among users
  • NETWORK_DISTANCE – Distance of relationship from the reference user

idspec

Assuming a group consisting person A, A’s friends and friends of the A’s friends, the developer can refer the group as “USER_ID – Viewer”, “GROUP_ID – “FRIENDS” and “NETWORK_DISTANCE – 2”. In a mixi App, the developer describes the group in a specific social graph based on these 3 parameters.

In the mixi App, only a list of Friends is available. This means that parameters can be specified either “SELF” (user her/himself specified by USER_ID) or “FRIENDS” for GROUP_ID and 1 for NETWORK_DISTANCE.

Requesting List of Friends’ Information

In order to obtain a list of Friends, opensocial.IdSpec object is created. This IdSpec object specifies the 3 conditions mentioned above. Based on the conditions, the developer is able to generate a request object by using the newFetchPeopleRequest() in the opensocial.DataRequest class.

var params = {};
params[opensocial.IdSpec.Field.USER_ID] = opensocial.IdSpec.PersonId.VIEWER;
params[opensocial.IdSpec.Field.GROUP_ID] = "FRIENDS";
var idSpec = opensocial.newIdSpec(params);
var req = opensocial.newDataRequest();
req.add(req.newFetchPeopleRequest(idSpec), "friends");
req.send(function(data) {
    if (data.hadError()) {
        var msg = data.getErrorMessage();
        // エラー発生時の処理
    } else {
        // 取得結果に対する処理
    }
});

In this sample code, the developer generates a params object and specifies a list of Friends of Viewers as the parameters of USER_ID and GROUP_ID in the opensocial.IdSpec.Field class. Then, an IdSpec object is generated from the opensocial.newIdSpec(). By using this IdSpec object as a parameter to call the newFetchPeopleRequest(),a request object for obtaining the list of Friends is generated.

Besides, by specifying certain profile information as a second parameter in the newFetchPeopleRequest(), specific pofile information items can be obtained at the same time.

var ip = {};
ip[opensocial.IdSpec.Field.USER_ID] = opensocial.IdSpec.PersonId.VIEWER;
ip[opensocial.IdSpec.Field.GROUP_ID] = "FRIENDS";
var idSpec = opensocial.newIdSpec(ip);
var dp = {};
dp[opensocial.DataRequest.PeopleRequestFields.PROFILE_DETAILS] = [
    opensocial.Person.Field.PROFILE_URL,
    mixi.PersonField.BLOOD_TYPE
];
var req = opensocial.newDataRequest();
req.add(req.newFetchPeopleRequest(idSpec, dp), "friends");
req.send(function(data) {
    if (data.hadError()) {
        var msg = data.getErrorMessage();
        // エラー発生時の処理
    } else {
        // 取得結果に対する処理
    }
});

The add() and send() in the DataRequest object can be used in the same way as one in the newFetchPersonRequest().

Retrieving Friend Information from Results

Multiple users are selected under the conditions specified by the IdSpec object. Therefore,,the way of handling a consequence within the callback function from a parameter of the send() is slightly different from the one in obtaining the profile information for a single user using the newFetchPersonRequest() from the step of obtaining the ResponseItem object. The following code is an example of processing a list of Friends. Error handling for the DataRequest object and ResponseItem object is omitted.

req.send(function(data) {
  var friends = data.get("friends").getData();
  friends.each(function(friend) {
    var id = friend.getId();
    var nickname = friend.getDisplayName();
    var thumbnailUrl = friend.getField(opensocial.Person.Field.THUMBNAIL_URL);
    // プロフィール情報を使って処理
  });
});

The object obtained from the getData() in the ResponseItem object is an object in the opensocial.Collection class. In the sample code , this Collection object stores a list of Friends, that means multiple Person objects containing the profile information of each user.

By using the each() in the Collection object, each of objects stored in the Collection object can be handled one by one. That is, by specifying the callback function to the each() , each object executes the callback function and passes the specific object as a parameter. In this sample code, the Person objects are specified as the parameters, and the developer displays the obtained profile information from the Peron objects with the getDisplayName().

Paging Process

Obtaining all profile information of the Friends is less feasible if a specific user connects a large number of Frinends. In this case, you can obtain a list of Friends from multiple processes by separating it into several pieces. This process is called paging.

In order to perform paging, the MAX and FIRST prescribed in the opensocial.DataRequest.PeopleRequestFields class are available. An example of usage is shown below.

var idSpec = opensocial.newIdSpec(...);
var params = {};
params[opensocial.DataRequest.PeopleRequestFields.MAX] = 10;
params[opensocial.DataRequest.PeopleRequestFields.FIRST] = 30;
var req = opensocial.newDataRequest();
req.add(req.newFetchPeopleRequest(idSpec, params), "people");
req.send(function(data) {
  var people = data.get("people").getData();
  var offset = people.getOffset();
  var total = people.getTotalSize();
  var size = people.size();
  var msg = total + "件中 " + offset + " - " + (offset + size) + " 件目";
  // do something...
});

MAX enables the developer to specify the maximum number of profile information to be obtained per request and FIRST enables to specify from which profile information to be obtained in a specific user group determined in the IdSpec object. In addition, total number of the profile information and the number of profile information obtained in a process can be obtained from the Collection object. In the sample code, the number of profile information obtained out of the total number is displayed.

Acquisition of only Friends Using the mixi App

In most cases, the developer is willing to obtain the list of Friends who use the same mixi App. Specifiying Person objects obtained from the newFetchPeopleRequest()

var person = ...;
var hasApp = person.getField(opensocial.Person.Field.HAS_APP);

enables the developer confirm each of Friends are using the specific mixi App. In the case that the developer wants to obtain the list of Friends who use the specific mixi App from the beginning, newFetchPeopleRequest() is described in OpenSocial in order to filter the list of Friends. The mixi App specification also support “HAS_APP” filter. opensocial.DataRequest.PeopleRequestFields.FILTER can be used for filtering.

var idSpec = ...;
var req = opensocial.newDataRequest();
var params = {};
params[opensocial.DataRequest.PeopleRequestFields.FILTER] = opensocial.DataRequest.FilterType.HAS_APP;
req.add(req.newFetchPeopleRequest(idSpec, params), "friends");
req.send(function(data) {
  var friends = data.get("friends").getData();
  friends.each(function(friend) {
    // do something...
  });
});

FilterType.HAS_APP can be specified in the params object as a value of FILTER and the value is specified as the second parameter of the newFetchPeopleRequest(). Thus, only the list of Friends owning the specific mixi App can be obtained in the friend variable in this sample code.

In filtering, paging (MAX, FIRST) is available at the same time. By combining these functionalities, the developer is able to improve the user experience including minimizing the launching application time.

Error Codes

In calling Person & Friends API, some error codes may be availables. By getErrorCode() in ResponseItem object, the developer is able to obtain these error codes. Analyzing these codes, the developer can determine what cause these errors and how to handle them.

Error Code Reference
400 (BAD_REQUEST) Inappropriate paging parameter or authentication, or No target ID is specified.
403 (FORBIDDEN) No Authorization or a selector including @self or @friends is not specified
404 (NOT_FOUND) Inappropriate target user ID or a specified user is not found,
500 (INTERNAL_SERVER_ERROR) mixi internal error

TOP OF THIS PAGE