">mixi Developer Center (mDC)

mixi Apps

mixi Apps (English) » Technical Specification » PC » Information Sharing

Information Sharing

In a general application, writing input information and content to a file and/or database to store the data regardless of the application’s usage.

In most cases, the developer considers storing the input information or content obtained from external services in the mixi App.If a mixi App prompts its users to enter information every time they use it, the application cannot be successful. Furthermore, there may be a case that a certain user’s information can be referred from other users especially for a content/information sharing application.

appdata1

The OpenSocial JavaScript APIs prescribe that OpenSocial containers provide the data store functionality and the API is called the Persistence API in OpenSocial. This API enables a developer to store the data and share the data without building own database.

Functions Provided by Persistence API

In the mixi App, the input data can be stored and shared through the Persistence API. It is necessary to describe the process based on “who owns the information”. That is, specifying “whose information is obtained” is required in obtaining and/or sharing the data.

The following functions are available:

  • Name certain data and store the data
  • Retrieve persistent data
  • Clear persisitent data

The data can be controlled for individual application + user. The data for a different mixi App is not accessible. Moreover, Only a Viewer is able to store the data in his/her field as an owner of such data, not another user’s.

On the contrary, obtaining not only the data of the Viewer, but also the one of other users is permitted. That is, it is possible to obtain the data of the Viewer’s friends.

In the mixi App specification, Key-Value pair string is supported.

Persistence of Data

A simple example of data is shown below.

var msg = "Oops! ><";
var req = opensocial.newDataRequest();
req.add(req.newUpdatePersonAppDataRequest(opensocial.IdSpec.PersonId.VIEWER, "comment", msg), "response");
req.send(function(data) {
  if (data.hadError()) {
    var msg = data.getErrorMessage();
    // do something...
  } else {
    var response = data.get("response");
    if (response.hadError()) {
      var code = response.getErrorCode();
      // do something...
    } else {
      // do something...
    }
  }
});

To work with persistent data, by the opensocial.DataRequest.newUpdatePersonAppDataRequest() , a key-value pair can be stored. The following arguments can be specified by this function.

  • User ID
  • Key string of data to be stored
  • String of data to be stored

The user ID must be Viewer’s. Storing the data in other users’ fields is not allowed in the mixi Platform for the security purpose. Either opensocial.IdSpec.PersonId.VIEWER or the Viewer ID should be specified.

The key string of data is required when retrieving the persistent data later on. If this function is first called with this key string, the key string is newly created. Then, second time and onward, the persistent data is updated. The third argument can be given by a string of persistent data.

By adding the request object from the newUpdatePersonAppDataRequest() to the DataRequest object, a request is sent to a server via the send() . The callback function specified in the parameter of the send() enables the developer to check if the data is successfully stored.

Multiple key-value pairs can be stored by calling the newUpdatePersonAppDataRequest() l to generate as many request objects as the number of key-value pairs to be stored.

Retrieving Persistent Data

In retrieving the persistent data, the developer has to identify “whose persistent data is to be retrieved.” The Persistence API enables the developer to retrieve the stored data of multiple users at the same time. The opensocial.IdSpec class can be utilized in order to identify a group of users.

The newFetchPersonAppDataRequest()provided by the Persistence API is available to retrieve other users’ persistent data. The list below is an example of retrieving persistent data of Friends of a Viewer. Error handling is omitted in this example.

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.newFetchPersonAppDataRequest(idSpec, ["comment"]), "response");
req.send(function(data) {
  var response = data.get("response").getData();
  for (var id in response) {
    var msg = response[id]["comment"];
    // do something...
  }
});

Here, an IdSpec object is created based ona conditionof a group of the Viewer’s Friends and the persistent data is retrieved by passing the result from an IdSpec object to to an argument of the newFetchPersonAppDataRequest(). In this case, a key name for retrieving information is specified in an array where the developer can decribe multiple key-value pairs to create multiple requests spontaneously.

The data can be retrieved from the argument of callback function passed to the send(). The data is stored referring a user ID as a property name. Each persistent data can be retrieved by obtaining an object by each ID and identifying key-value pair as a property name.

In the case of retrieving all persistent data, “*” can be used as wild card, instead of specifying all key strings in an array.

req.add(req.newFetchPersonAppDataRequest(idSpec, "*"), "response");

Clearing Persistent Data

The developer is able to clear stored data that is not necessary by the newRemovePersonAppDataRequest() in the opensocial.DataRequest class.

The list below is an example of clearing stored data.

var req = opensocial.newDataRequest();
req.add(req.newRemovePersonAppDataRequest(
    opensocial.IdSpec.PersonId.VIEWER, ["comment"]), "response");
req.send(function(data) {
  var response = data.get("response").getData();
  if (response.hadError()) {
    var code = response.getErrorCode();
    // do something...
  }
});

Only a Viewer is permitted to remove the data. That is, the first argument of the newRemovePersonAppDataRequest() should be opensocial.IdSpec.PersonId.VIEWER for.

For the second parameter, a key string for the data to be cleared or “*,” can be specified.. In order to operate a mixi App stably, the developer should implement an error check from the parameter of the callback function resulted from the send() if the persistent datai is successfully deleted by.

Data Storage Capacity

The maximum amount of data storage prescribed by the Persistence API is as follows:

  • Up to 64 KB for a string per key
  • Up to 10 MB for the total of strings for all keys available per application per user

* A double byte code is counted as 3 bytes (UTF-8).

Error Codes

In calling Persistence 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 causes these errors and how to handle them.

Error Code Reference
400 (BAD_REQUEST) Specifying inappropriate Key/Value, more than 100 Key/Value, prohibited character usage for Key, no authentication, or no target ID is specified
403 (FORBIDDEN) No Authorization or a selector including @self or @friends is not specified
500 (INTERNAL_SERVER_ERROR) mixi internal error

 

TOP OF THIS PAGE