mixi Developer Center (ミクシィ デベロッパーセンター)

mixiアプリの特徴は、何と言ってもプロフィール情報や友人の情報を使ったソーシャル性にあります。mixiアプリが採用している OpenSocialは、プロフィール情報や友人の情報にアプリケーションからアクセスするための機能を規定しています。プロフィール情報や友人の情報を扱うための手順を最初に習得することは、mixiアプリ開発を理解する上での近道です。

mixiアプリでは、ユーザのプロフィール情報として、以下の情報を扱うことが可能です。また、これに加えて、友人一覧も取得することが可能となっています。これらの取得処理は、OpenSocial JavaScript APIにて定められているPerson & Friends APIを利用することになります。

• ID
• ニックネーム
• プロフィール写真
• プロフィールURL
• 現住所(県のみ)
• 年齢
• 生年月日
• 性別
• 血液型

mixiアプリは、mixiの各ユーザの画面に埋め込まれて実行されるソーシャルアプリケーションです。そのため、ユーザを扱うためのソーシャルアプリケーションならではの考え方があります。まずはそれから紹介しましょう。

OwnerとViewer

mixiアプリは、ユーザがアプリ検索画面を使って面白そうなアプリケーションを探したり、アクティビティフィードや招待などによって新しいアプリケーションを発見することになります。もし気に入ったOpenSocialアプリケーションが見つけて使い始めるためには、ユーザはそのアプリケーションをインストールしなければなりません。インストールされたアプリケーションは、自分のホーム画面のアプリ一覧に掲載され、いつでもそのアプリケーションを楽しむことができるようになります。

つまり、mixiアプリには「持ち主」という概念があるということです。例えば、ある占いアプリケーションを、AさんとBさんがそれぞれインストールしていれば、「Aさんの占いアプリケーション」「Bさんの占いアプリケーション」ということになります。この持ち主のことを、OpenSocialでは「Owner」と呼んでいます。

さて、Aさんが持ち主の占いアプリケーションは、Aさんのプロフィール画面に配置されることもあれば、Aさんがその占いアプリケーションを使った結果のアクティビティフィードが掲載されることもあります。ここで、別のユーザCさんが、Aさんのプロフィール画面を訪れた際に、その占いアプリケーションがプロフィール画面に配置されていたとします。この場合、占いアプリケーションの持ち主はAさんですが、そのアプリケーションを操作しているのはCさんです。

実際にアプリケーションを操作するユーザのことを、OpenSocialでは「Viewer」と呼んでいます。上記の例では、Cさんは占いアプリケーションのViewerとなったことになります。もちろん、あるユーザが自分のホーム画面からインストールしたアプリケーションを利用した場合は、 OwnerとViewerの両方とも、そのユーザとなります。

mixiアプリの開発者は、そのアプリケーションの実行時に「誰に実行されているのか？」「誰のアプリケーションが実行されているのか？」という点を意識した設計と実装を行うことが求められます。さらに、そのアプリケーションがどのビューで実行されているのか、という観点も、Ownerと Viewerの区別と合わせて意識することが必要です。例えば、Canvasビューでmixiアプリが実行されている場合には、そのアプリケーションの機能を利用するのはViewerとなるので、そのアプリケーションはViewerに対して機能やコンテンツの提供を行うでしょう。それに対して、 Profileビューでmixiアプリが実行されている場合は、プロフィール画面を見ている閲覧者に、プロフィール画面に情報が掲載されているユーザ、つまりOwnerに関するコンテンツを提示することが中心となるため、そのアプリケーションはOwnerに関係した情報を取得し表示するでしょう。

プロフィール情報や友人の情報にアクセスする際には、OwnerとViewerの使い分けを正しく行うことが求められます。この違いによって、取得できる情報と取得できない情報の区別が発生する場合もあるため、この概念をぜひ把握しておいてください。

プロフィール情報の取得

mixiアプリが扱う最も特徴的であり、かつ基本的な情報は、ユーザのプロフィール情報です。プロフィール情報を使用することで、mixiアプリはそのユーザにとって有益なコンテンツをカスタマイズして提供することができるようになります。mixiアプリ内から、OpenSocialにて規定されているJavaScript APIのいくつかを利用することで、mixiのサーバからOwnerやViewer、その他のユーザのプロフィールを取得することが可能です。

ユーザのプロフィール情報の取得をリクエストする

mixiアプリの利用ユーザ(Viewer)のプロフィール情報を取得するためのコードの例を、以下のリストに示します。

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 {
        // 取得結果に対する処理
    }
});

OpenSocial JavaScript APIでは、情報の取得や更新などをサーバに依頼する際に、opensocial.DataRequestオブジェクトに対して各種リクエストオブジェクトを生成して追加していき、それらをまとめて処理を行うように規定されています。

まず、リクエストを送る処理を担当するDataRequestオブジェクトを、newDataRequest()関数により生成します。次に、生成したDataRequestオブジェクトが提供するnewFetchPersonRequest()関数を使用して、あるユーザのプロフィール情報を要求するためのオブジェクトを生成し、さらにadd()関数にて要求オブジェクトをDataRequestオブジェクトに追加しています。

newFetchPersonRequest()関数の第1引数には、取得したいユーザを特定するための値を指定します。この際、以下のどれかを指定することになります。

• Viewer(アプリケーションを操作するユーザ) – opensocial.IdSpec.PersonId.VIEWER
• Owner(アプリケーションの持ち主) – opensocial.IdSpec.PersonId.OWNER
• 任意のユーザ – 取得したいユーザのID

直接ユーザのIDを指定してプロフィール情報を取得することが基本となりますが、ViewerやOwnerのプロフィール情報を取得したい場合は、IdSpec.PersonIdクラスに規定されている定数を使えば良いでしょう。

DataRequestクラスのadd()関数を利用する際に、第1引数にnewFetchPersonRequest()関数などで生成されたリクエストをオブジェクトを指定します。そして、第2引数には、このリクエストの結果を取り出すために使用することになるキー文字列を渡しておきます。

リクエストオブジェクトの追加後、send()関数を呼び出すことによって、実際にmixiのサーバにmixiアプリからプロフィール情報の取得要求が送信されます。mixiサーバからの結果を受信した際に、send()関数の引数に指定したコールバック関数が呼び出されます。つまり、サーバへの処理要求と結果の受信は、非同期となりますので、ご注意ください。

コールバック関数に渡される引数に対して、hadError()関数を使うことで、何かエラーが発生したかどうかをチェックすることができます。その結果エラーが発生していた場合は、getErrorCode()関数またはgetErrorMessage()関数を呼び出してエラーの状況を取得し、ユーザに提示するなどの処理を行ってください。このエラー処理は、省略せずに必ず実装することが、mixiアプリの安定した動作のために求められます。

取得結果からプロフィール情報を取り出す

では、サーバから取得したプロフィール情報を実際に取り出すコードを見ていきましょう。

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);
          // プロフィール情報を使った処理
        }
    }
});

コールバック関数の引数には、正確にはopensocial.DataResponseクラスのオブジェクトが渡されます。この DataResponseオブジェクトのget()関数を使って、リクエストオブジェクトの結果を持つオブジェクトを個々に取り出します。その際に、 DataRequestオブジェクトのadd()関数で指定したキー文字列を使うことになります。

get()関数を使って得られるオブジェクトは、opensocial.ResponseItemクラスのオブジェクトとなります。これは、ある1 つのリクエストオブジェクトの結果を保持するためのオブジェクトです。このResponseItemオブジェクトについても、hadError()関数や getErrorCode()関数などのエラー処理関連の関数が備わっています。先ほどのDataResponseオブジェクトは、複数のリクエスト全体に対するエラー情報であり、ResponseItemオブジェクトは、個々のリクエストに対するエラー情報となります。

newFetchPersonRequest()関数によって生成された、ある特定のユーザのプロフィール情報の取得結果は、 ResponseItemオブジェクトのgetData()関数を使って取り出すことができます。getData()関数の呼び出し結果は、この場合 opensocial.Personクラスのオブジェクトとなります。このPersonオブジェクトは、文字通りプロフィール情報を保持しているオブジェクトです。

プロフィール情報の中で、IDとニックネームに関しては、専用の関数が提供されています。

• ID – getId()関数
• ニックネーム – getDisplayName()関数

その他の情報を取り出すためには、getField()関数を使います。このgetField()関数の引数として、取得したい情報の種別を指定します。この種別は、opensocial.Person.Fieldクラス、およびmixi.PersonFieldクラスの定数として定義されています。上記のリストでは、opensocial.Person.Field.THUMBNAIL_URL定数をgetField()関数の引数として指定することで、ユーザのサムネイル画像のURLを取得しています。

多くのプロフィール情報の取得をリクエストする

上記の例では、newFetchPersonRequest()関数の呼び出し時に、引数は1つしか指定していませんでした。この場合、取得可能なユーザのプロフィール情報の種別は、

• ID – getId()
• ニックネーム – getDisplayName()
• プロフィール写真 – getField(opensocial.Person.Field.THUMBNAIL_URL)

に限定されています。これは、ユーザが持つ全てのプロフィール情報を無条件にネットワーク上にて送受信することは、それだけで帯域を圧迫する可能性がある、という理由から来ています。

上記の3つの項目以外の情報を取得するためには、どの項目を得たいかを明示的に指定することが求められます。その指定を行うために、 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) {
  // プロフィール情報使った処理
});

PROFILE_DETAILSをキーとして、取得したい項目を配列で指定しています。このparamsオブジェクトを newFetchPersonRequest関数の第2引数に指定することで、多くの情報を取得することが可能です。上記のリストでは、mixiアプリとして取得可能な全ての項目を指定しています。PROFILE_DETAILSにて指定された各項目は、それぞれPersonオブジェクトの getField()関数で取得することになります。その例を以下に示します。なお、エラー処理は省略しています。

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は、取得したユーザがこのアプリケーションをインストールしているかどうかを論理値で得るための項目となります。

友人情報の取得

今までは、ある一人のユーザのプロフィール情報を取得するための方法を紹介してきました。これ以外にも、mixiアプリでは「友人のユーザのプロフィール情報の取得」をサポートしています。この友人情報の取得が可能になることで、mixiアプリは友人の一覧を扱うことによってソーシャル性を持つことができるようになります。

ユーザとグループとは

OpenSocialでは、あるユーザの集合を取得したい場合、その集合に当てはまる条件として、以下の3つを指定することができるように規定されています。

• USER_ID – 基準となるユーザのID
• GROUP_ID – ユーザ間の関係
• NETWORK_DISTANCE – 基準ユーザからの関係の距離

例えば「アプリケーションの利用者Aさんの友達の友達の集合」であれば「USER_ID – Viewer」「GROUP_ID – “FRIENDS”」「NETWORK_DISTANCE – 2」という指定となります。ソーシャルグラフの中で、この3つの条件を元に、ユーザの集合を特定するわけです。

mixiアプリで取得することができるのは、友人の一覧です。つまり、GROUP_IDとして指定可能な値は、”SELF”(USER_IDで指定されたユーザ自身)もしくは”FRIENDS”のどちらかとなります。そして、NETWORK_DISTANCEは1固定となります。

友人一覧情報の取得をリクエストする

友人一覧を取得するために、まずは友人のユーザの集合という条件を持つopensocial.IdSpecオブジェクトを作成します。この IdSpecオブジェクトは、先ほどの3つの条件を保持するオブジェクトです。この条件を元に、opensocial.DataRequestクラスにて規定されているnewFetchPeopleRequest()関数を使って、リクエストオブジェクトを生成します。

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 {
        // 取得結果に対する処理
    }
});

paramsオブジェクトを生成し、opensocial.IdSpec.Fieldクラスにて規定されているUSER_IDおよび GROUP_IDを使って、Viewerの友人一覧を条件として指定しています。そして、opensocial.newIdSpec()関数にて、 IdSpecオブジェクトを生成しています。このIdSpecオブジェクトを引数としてnewFetchPeopleRequest()関数を呼び出すことで、友人一覧を取得するためのリクエストオブジェクトを生成することができます。

上記のリストに加えて、PROFILE_DETAILSによるプロフィール情報の取得項目の指定も同時に行うことができます。下のリストのように、newFetchPeopleRequest()関数の第2引数を使うことができます。

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 {
        // 取得結果に対する処理
    }
});

DataRequestオブジェクトのadd()関数およびsend()関数の使い方は、newFetchPersonRequest()関数の場合と同じです。

取得結果から友人情報を取り出す

IdSpecオブジェクトにより指定された条件で決定されるユーザの数は複数となります。そのため、send()関数の引数で渡すコールバック関数内での結果の扱いについては、newFetchPersonRequest()関数を使用した一人のプロフィール情報を取得する場合と比べて若干異なりますが、ResponseItemオブジェクトを得るところまでは同じです。以下のコードは、友人一覧を処理するための例です。DataRequest オブジェクトおよびResponseItemオブジェクトに対するエラー処理は省略しています。

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);
    // プロフィール情報を使って処理
  });
});

ResponseItemオブジェクトのgetData()関数を呼び出した結果得られるオブジェクトは、 opensocial.Collectionクラスのオブジェクトとなります。上記の例では、このCollectionオブジェクトには、取得結果である友人の一覧、つまり各友人のユーザのプロフィール情報を持つPersonオブジェクトが複数格納されています。

Collectionオブジェクトのeach()関数を使うことで、Collectionオブジェクト内に格納されているオブジェクトを1つずつ処理することが可能です。つまり、each()関数にコールバック関数を指定することにより、オブジェクトごとにコールバック関数が呼び出され、対象のオブジェクトが引数として渡されます。ここではPersonオブジェクトが渡されるため、そのオブジェクトからgetDisplayName()関数などを使ってプロフィール情報を取得し、画面に表示するなどの処理を行います。

友人の人数が多かった場合のページング処理

取得対象のユーザの友人の人数がとても多かった場合、その人数分プロフィール情報を取得することは現実的ではありません。そのため、複数回に分けて友人の一覧を取得することができます。このような分割した取得を、ページングと呼びます。

ページングのために、opensocial.DataRequest.PeopleRequestFieldsクラスにて規定されているMAXおよびFIRST定数を利用することができます。以下は、その利用例です。

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には、1リクエストあたりの取得される最大の件数を指定します。そしてFIRSTには、IdSpecオブジェクトで特定されるユーザの集合の中で、何件目から取得するかを指定します。取得結果のCollectionオブジェクトからは、各種関数を使って、取得された件数や全体の件数などを得ることが可能です。これらを使用して、上記の例のようにページ処理を画面に表示するなどすればよいでしょう。

mixiアプリを利用している友人のみの取得

mixiアプリが友人を扱う場合に、そのmixiアプリをインストールしているユーザのみの一覧取得を行いたい場面は、とても多いことでしょう。newFetchPeopleRequest()関数にて取得されるPersonオブジェクトに対して、

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

とすることで各友人が対象mixiアプリを持っているかを確認することができます。しかし、最初からこの結果がtrueの友人のみを取得したい場合はどうしたら良いでしょうか。

OpenSocialでは、newFetchPeopleRequest()関数にてユーザの一覧を得る際に、フィルタをかけることができます。mixiアプリにおいても、「HAS_APP」フィルタの指定をサポートしています。フィルタをかけるために、opensocial.DataRequest.PeopleRequestFields.FILTERを利用します。

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...
  });
});

FILTERの値としてFilterType.HAS_APPを指定したparamsオブジェクトを準備し、newFetchPeopleRequest()関数の第2引数として指定します。その結果、上記のリスト内のfriend変数には、対象mixiアプリを所有するユーザのみが得られることになります。

フィルタの利用について、同時にページング（MAX、FIRST）も使用することが可能です。これらの機能をうまく利用することで、mixiアプリの起動時間などの短縮を図ることが可能になりますので、積極的に利用すると良いでしょう。

エラーコード

Person & Friends APIの呼び出し時に、いくつか結果として得られる可能性があるエラーコードがあります。これらのエラーコードは、ResponseItemオブジェクトのgetErrorCode()関数を呼び出すことによって得ることが可能です。エラーコードの種別によって、適切な処理を行ってください。