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

mixiアプリにおいて、友人とのコミュニケーションは非常に重要です。友人がmixiアプリでどのように楽しんでいるのか、これを知りたいと思うことがmixiアプリを繰り返し利用することの大きなモチベーションとなります。

OpenSocialでは、更新情報のことをアクティビティと呼んでいます。mixiアプリにおけるアクティビティの利用価値は、API全体の中でも非常に高く位置づけられています。OpenSocial JavaScript APIでは、OpenSocialアプリケーション内からアクティビティを作成し公開する機能を規定しています。mixiアプリでは、画像を含むアクティビティを作成することも可能です。画像の利用によって、アクティビティはより友人の目に留まることになるでしょう。

(画像は縦76px 横76pxです)

アクティビティの作成と公開は、OpenSocialアプリケーションを実行しているユーザ(すなわちViewer)に対して行われます。つまり、作成されたアクティビティの持ち主は、mixiアプリを実行したユーザということになります。作成および公開されたアクティビティは、例えばそのユーザのプロフィール画面にあるフィード一覧に掲載され、さらにそのユーザの友人のページにおいても掲載されることになります。

アクティビティの種類

コミュニケーションフィードの投稿を行うためのAPIを呼び出した際に、そのまま投稿されるのではなく、ユーザに投稿を行ってよいかどうかを問い合わせるポップアップウィンドウが表示されます。そこでユーザが許可を行った場合にのみ、コミュニケーションフィードは投稿されます。その結果、投稿されたコミュニケーションフィードは、友人のhome.plにて表示されます。

アクティビティの送信

OpenSocial JavaScript APIによるアクティビティの送信は、以下の手順が必要となります。

• アクティビティの情報を持つopensocial.Activityオブジェクトを生成する。
• opensocial.requestCreateActivity()関数を使って、アクティビティの作成をサーバに依頼する。

もし画像を伴うアクティビティを作成したい場合は、Activityオブジェクトを生成する際に、opensocial.MediaItemオブジェクトを生成することも必要となります。

opensocial.Activityオブジェクトを生成する

アクティビティを作成し公開するために、まずはopensocial.Activityオブジェクトを生成します。このActivityオブジェクトに、具体的なアクティビティの情報を保持させます。以下のリストは、文字列のみを持つシンプルなActivityオブジェクトを作成する例です。アクティビティの文字列は、opensocial.Activity.Field.TITLEにて指定します。

var params = {};
params[opensocial.Activity.Field.TITLE] = "Hello!";
var activity = opensocial.newActivity(params);

指定されたアクティビティの文字列は、255文字までが有効になります。256文字目以降は切り捨てられますので、ご注意ください。

上記に加えて、画像を伴うアクティビティも作成することが可能です。その場合は、opensocial.MediaItemオブジェクトを作成します。以下のリストは、画像を伴うアクティビティの作成例です。MediaItemオブジェクトは、opensocial.newMediaItem()関数を使って生成することができます。この際に、MIME Typeと画像のURL、そして画像を示すパラメータを引数として渡します。

var mediaItem = opensocial.newMediaItem("image/gif", "http://your.server.host/image.gif");
var ap = {};
ap[opensocial.Activity.Field.TITLE] = "Hello!";
ap[opensocial.Activity.Field.MEDIA_ITEMS] = [mediaItem];
var activity = opensocial.newActivity(ap);

MediaItemオブジェクトは、opensocial.Activity.Field.MEDIA_ITEMSフィールドとして配列で指定します。mixiアプリでは、3個までMediaItemオブジェクトを配列に指定することが可能です。

MediaItemオブジェクトとして指定する画像は、横76px、縦76pxの画像を指定するようにしてください。それ以外のサイズの画像が指定された場合に関しても、76×76の大きさで表示されることになります。

アクティビティの作成と公開をサーバに依頼する

生成したActivityオブジェクトは、このままでは何も起きません。サーバに対して、アクティビティの生成を改めて依頼することが必要となります。そのために、opensocial.requestCreateActivity()関数を使用します。以下のリストは、作成されたActivity オブジェクトの内容を元に、アクティビティの作成と公開をサーバに依頼する例です。

var activity = ...;
opensocial.requestCreateActivity(
        activity, opensocial.CreateActivityPriority.HIGH, function(response) {
  if (response.hadError()) {
    var code = response.getErrorCode();
    // do something...
  } else {
    // do something...
  }
});

requestCreateActivity()関数の第1引数には、先ほど生成したActivityオブジェクトを指定します。第2引数には、opensocial.CreateActivityPriority.HIGHを指定します。

第3引数は、アクティビティの公開処理が終了した後に呼び出されるコールバック関数を指定します。コールバック関数の引数として、 opensocial.ResponseItemオブジェクトが指定されます。このオブジェクトのhadError()関数を使って、アクティビティが正常に作成および公開されたかどうかを確認するようにしましょう。

宛先指定のアクティビティの作成

mixiアプリの中からアクティビティを作成する際に、アクティビティの関係者を2名まで指定することができます。これを「宛先指定のアクティビティの作成」と呼びます。そのためには、mixi.ActivitiyField.RECIPIENTSを利用します。

var user1 = ...; // 関係者その1のID
var user2 = ...; // 関係者その2のID
var params = {};
params[opensocial.Activity.Field.TITLE] = "Hello!";
params[mixi.ActivityField.RECIPIENTS] = [user1, user2];
var activity = opensocial.newActivity(params);

これにより作成されたアクティビティは、user1, user2で指定したユーザだけが閲覧できるようになります。

アクティビティの表示範囲について

あるユーザAの友人がmixiアプリを使った結果送信されたアクティビティが、そのユーザAのページに掲載されるかどうかは、そのmixiアプリのステータスによって決まります。具体的には、以下の表となります。

アクティビティの遷移先の指定

送信するアクティビティをユーザがクリックした際のリンク先について、mixiアプリはいくつか指定を行うことができます。そのために、opensocial.Activity.Field.URLを利用します。これを指定しなかった場合は、アクティビティが送信された際の利用者をOwner IDとするアプリ画面（run_appli.pl）へのリンクとなります。これ以外に、mixiアプリは以下のカスタマイズを行うことが可能です。

• 遷移先のページ – run_appli.plもしくはview_appli.pl（アプリ紹介画面）
• mixiアプリ起動時に渡したいパラメータ – appParams

パラメータを指定できることで、特定のアクティビティからのmixiアプリ起動時に動きを変化させる、などの工夫を行うことができます。例えば選択されたアイテムのIDとその個数をアクティビティに含めてmixiアプリ起動時にそれを受け取りたい場合には、以下のように記述します。

var appId = ...; // アプリID
var data = {};
data[opensocial.Activity.Field.TITLE] = ...;
var params = {
    item_id: "12345",
    count: "3"
};
var escaped = gadgets.io.encodeValues({
    appParams: gadgets.json.stringify(params)
});
data[opensocial.Activity.Field.URL] = "http://mixi.jp/run_appli.pl?id=" + appId + "&" + escaped;
var activity = opensocial.newActivity(data);
opensocial.requestCreateActivity(
    activity,
    opensocial.CreateActivityPriority.HIGH,
    function(res) {...}
);

mixiアプリ起動時にパラメータを取得するには、以下のように記述します。これに加えて、Gadget XMLにを記述しておく必要があります。

var params = gadgets.views.getParams();
var itemId = params["item_id"];
var count = params["count"];
// do something...

もしアプリ画面ではなく、アプリ説明画面（view_appli.pl）に遷移させたい場合は、上記のURL内の“run_appli.pl”の箇所を“view_appli.pl”に変更してください。

URLとして、http://mixi.jp/以外のサイトや、view_appli.plおよびrun_appli.pl以外の画面、異なるアプリIDの指定を行うとエラーとなりますので、ご注意ください。

エラーコード

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