/** \file 
\brief はじめにお読みください。

\section はじめに

mixi API SDK for iOSは開発者の方がiOSネイティブのmixiアプリをできる限り簡単に開発することができるように開発されました。

\subsection 特徴

mixi API SDK for iOSの特徴は、以下の通りです。

- 個人・法人に関わらず、個人パートナー登録すればどなたでも開発可能
- OAuth 2.0の認証/認可手順の実装が不要
- Tokenの取得/更新を自動化
- APIコールを統一的な手順で実行可能
- シングルサインオンが可能でユーザ認可時のパスワード入力不要

\subsection サポート端末

本SDKにてサポートするiOS端末は以下の通りです。

- iPhone（iOS4.0以降搭載） **1

**1 iPadについては、対応未定

\subsection 利用可能なAPI

- mixiアプリ
  - People API
  - Groups API
  - Photo API
  - Request API
  - Communication Feed **2
- Graph API **3
  - People API
  - Groups API
  - People lookup API
  - Voice API
  - Updates API
  - Check API
  - Photo API
  - Message API
  - Diary API
  - Check-in API
  - Profile Image API

なお、Geolocation APIについてはTouch版/モバイル版と異なり、弊社への許諾なしに利用することが可能です。

**2 Communication Feedについては、今後提供予定

**3 基本的に提供されているすべての Graph API が利用可能です。

\section SDKダウンロード

mixi API SDK for iOS を利用するには、以下のファイルをダウンロードしてください。
ダウンロードすると、mixi API SDK for iOS の利用規約に同意したものと見なされます。

[mixiIOSSDK-1.3.6.zip](http://developer.mt.mixi.co.jp/connect/appli/spec/ios/download/mixiIOSSDK-1.3.6.zip) v1.3.6 716KB  2012-04-06

\subsection 更新履歴

v1.3.6 2012-04-06
- 不具合修正（mixiアプリでのSDK単独認可を停止）

v1.3.5 2011-04-02
- @throw を NSException#raise に変更

v1.3.4 2012-03-28
- Graph APIのSDK単独認可においてツールバーの「閉じる」ボタン押下を通知
- 不具合修正（エラーコード変更・公式アプリダウンロード）

v1.3.3 2012-03-15
- 不具合修正（UserDefaults）

v1.3.2 2012-03-01
- 不具合修正（リクエストAPIキャンセル通知）

v1.3.1 2012-02-21
- リクエストAPIキャンセル通知

v1.3 2012-02-13
- mixi公式iPhoneアプリを使用せずにGraph APIを認可
- ディレクトリ構造変更
- 不具合修正（ボイス取得API）

v1.2.1 2011-12-28
- 不具合修正（メモリリーク）

v1.2 2011-10-31
- mixi_apps2スコープの導入とmixi_appsスコープの廃止
- 不具合修正（リクエストAPI呼び出し、MixiConfigのappIdプロパティ削除）

v1.1 2011-09-30
- mAP対応

v1.0 2011-09-20
- 提供開始


\section アプリケーションの登録

本SDKを用いてiOSアプリを開発するための手順を説明します。

\subsection mixiアプリ

SDKを利用するには、あらかじめ Partner Dashboard (http://sap.mixi.jp) にてアプリケーションが登録されている必要があります。まず、Partner Dashboard の mixiアプリ登録ページにて登録を行なってください。その際、対応デバイスの項目で「スマートフォンに対応(iOS版)」にチェックをすることでSDKが利用可能になります。

\subsection Graph API

SDKを利用するには、あらかじめ Partner Dashboard にてアプリケーションが登録されている必要があります。まず、Partner Dashboard の mixi Graph APIのサービス登録ページにてアプリケーションを登録をしてください。

その際、"起動URIスキーム"を以下を参考に登録してください。

\subsection 起動URIスキーム

ユーザがmixiサイト上のアプリケーション一覧やフィードをクリックした際に、WebブラウザからiOSアプリケーションが起動されることになります。この時に利用されるのが、起動URIスキームです。
初期値は以下の値に設定されています。

- mixiapp-<APP_ID>://run

この起動URIスキームの<APP_ID>の部分は変更可能です。できるだけ変更されることをお勧めします。変更を行う場合は、Partner Dashboardのアプリ設定ページから変更してください。
この起動URIスキームを実際にアプリケーションが受け取るためには、アプリケーションの Info.plist に適切な値を設定する必要があります。

\section プロジェクトの作成

SDK（mixiIOSSDK-[ver].zip）をダウンロードして展開し、lib/MixiSDKをプロジェクトのソースディレクトリに配置します。

\subsection iOSプロジェクトの作成

通常のiOSプロジェクト作成手順に従ってプロジェクトを作成します。

\subsection 必要なフレームワークの追加

mixi API SDK for iOSは次のフレームワークを必要とします。

- CFNetwork.framework
- Security.framework
- SystemConfiguration.framework

\subsection 起動URIスキームの追加

Partner Dashboardに登録した起動URIスキームをプロジェクトに追加します。

これで開発を始める準備は整いました。次からは、いよいよAPIの利用方法を説明していきます。

\section 初期化と認可処理

mixi API SDK for iOS を利用したアプリケーションを実際に開発する際のコードの記述方法について説明します。

\subsection ヘッダファイルの追加

SDKを利用する場合は次のヘッダファイルをインポートしてください。

<code>#import "MixiSDK.h"</code>

\subsection 初期化

mixi APIの呼び出しに使用するMixiクラスはシングルトンクラスです。インスタンスは次のようにして取得できます。

<code>[Mixi sharedMixi]</code>

ただし、APIを実行する前に一度シングルトンインスタンスを初期化しておく必要があります。
UIApplicationDelegate#application:didFinishLaunchingWithOptions:
例えばGraph APIを使用する場合、メソッド内で次のように記述するといいでしょう。
（全ての引数はアプリケーションの設定に合わせて変更してください）

<pre><code>Mixi *mixi = [[Mixi sharedMixi] setupWithType:kMixiApiTypeSelectorGraphApi 
                                    clientId:@"ab12c345de6789f12345" 
                                      secret:@"a1b2c3456d789ef0123ghi4567jklmn89op01qrs"];
[mixi restore];
[mixi reportOncePerDay];
</code></pre>

\subsection アプリの起動を通知

アプリの起動を通知するコードをapplicationWillEnterForeground:に追記します。

<pre><code>- (void)applicationWillEnterForeground:(UIApplication *)application {
    [[Mixi sharedMixi] reportOncePerDay];
}
</code></pre>

このコードの追記は任意ですが、サービスの改善のために協力していただけると幸いです。
アプリケーションの情報は一切送信されません。

\subsection 認可

mixiアプリのAPIを利用するためには、ユーザにAPI利用のための認可を行なってもらう必要があります。そのための画面を表示するのが authorize: メソッドです。

<code>[mixi authorize:@"r_profile", @"w_diary", nil];</code>

このメソッドを呼び出すことで、mixi公式アプリを利用してユーザーに認可を促す画面が表示されます。

さらに、公式アプリで行われる認可の結果（アクセストークンなど）を受け取るために
UIApplicationDelegate#application:openURL:sourceApplication:annotation:
メソッドに次のような処理を追加しておきます。

<pre><code>NSError *error = nil;
NSString *apiType = [[Mixi sharedMixi] application:application openURL:url sourceApplication:sourceApplication annotation:annotation error:&error];
if (error) {
　　// エラーが発生しました
}
else if ([apiType isEqualToString:kMixiAppApiTypeToken]) {
　　// 認可処理に成功しました
}
else if ([apiType isEqualToString:kMixiAppApiTypeRevoke]) {
　　// 認可解除処理に成功しました
}
</code></pre>

上記により認可が完了してればシングルトンオブジェクトはアクセストークンを保持し、APIを実行できる状態になっています。

\subsection 認可状態の確認

現在の認可状態を確認するには、以下のメソッドを利用します。

<code>Mixi#isAuthorized</code>

通常は、認可画面は初回のみ表示され、2回目以降はスキップすることが可能です。isAuthorizedメソッドはそのための確認処理を行います。既に認可済みであれば YES が返り、未認可であれば NO が返ります。

\subsection 認証解除

以下のメソッドを呼び出すことで認可状態の解除を行います。なお、mixi API SDK for iOS を利用する場合はユーザ保護の観点から、この認証解除機能を必ず実装してください。

<code>Mixi#revoke</code>

\subsection SDK単独で認可／認可解除を実行

Graph APIを利用する場合に限り公式アプリを経由せずにSDK単独で認可／認可解除を実行できます。

SDK単独での認可を行うには、mixiオブジェクトのauthorizerプロパティをMixiSDKAuthorizerインスタンスに置き換えてください。
UIApplicationDelegate#application:didFinishLaunchingWithOptions:内でMixiオブジェクトをsetupした直後に置き換えるといいでしょう。
redirectUrlはsap.mixi.jpでアプリケーションに設定したリダイレクトURLです。

<code><pre> if (![mixi isMixiAppInstalled]) {
    mixi.authorizer = [MixiSDKAuthorizer authorizerWithRedirectUrl:redirectUrl];
}
</pre></code>

<code>if (![mixi isMixiAppInstalled])</code>はmixi公式iPhoneアプリがなかった場合のみ、SDK単体で認可を行うようにするためのものです。
mixi公式iPhoneアプリの有無にかかわらず、必ずSDK単体で認可を行う場合はこのif文は不要です。
また、SDK単独で認可を行う場合は認可情報はSDK内部でやりとりされるため、先の項で説明した
UIApplicationDelegate#application:openURL:sourceApplication:annotation:
での処理も不要になります。

SDK単体で認可する場合は、さらにauthorizerが認可に使用するウェブビューコントローラの親になるビューコントローラを設定しなければいけません。
APIを呼び出すビューコントローラのUIViewController#viewDidAppear:に次のようなコードを追加してください。

<code><pre> - (void)viewDidAppear:(BOOL)animated
{
    [super viewDidAppear:animated];
    Mixi *mixi = [Mixi sharedMixi];
    if (![mixi isMixiAppInstalled] && ![mixi.authorizer isAuthorized]) {
        id authorizer = mixi.authorizer;
        [authorizer setParentViewController:[self navigationController]];
    }
}
</pre></code>

こちらも<code>![mixi isMixiAppInstalled] &&</code>はmixi公式iPhoneアプリがなかった場合にSDK単体で認可を行うようにするためのものです。
mixi公式iPhoneアプリの有無にかかわらずSDK単体で認可を行う場合は上の条件式は不要です。

\section APIの利用

API にアクセスするメソッドは複数ありますが、代表的なメソッドはMixi#sendRequest:delegate: です。本メソッドを利用して、統一的な利用で様々なAPIをコールすることが可能です。

ここでは、APIを呼び出すためのsendRequest:delegate:メソッドの簡単な例を紹介します。各APIに必要なパラメータの意味や戻り値など個々のAPIに関する詳細情報については、SDKに添付されているリファレンスを参照してください。

APIはエンドポイントとパラメーターを設定した<code>MixiRequest</code>インスタンスを、<code>Mixi#sendRequest:delegate:</code>メソッドに渡すことで実行します。
API実行前に認可が完了しているかどうかを確認して、未認可の場合は先に認可しておきます。認可に失敗した場合はmixi公式アプリがインストールされていないか、最新版ではない可能性があるので、AppStoreのmixi公式アプリのページを開きます。

<pre><code>if ([mixi isAuthorized]) {
    MixiRequest *request = [MixiRequest requestWithEndpoint:＠"/people/＠me/＠friends"];
    [mixi sendRequest:request delegate:mixiDelegate];
}
else if (![mixi authorizeForPermission:＠"r_profile"]) {
    MixiWebViewController *vc = MixiUtilDownloadViewController(self, @selector(closeDownloadView:));
    vc.orientationDelegate = self;
    [self presentModalViewController:vc animated:YES];
}
</code></pre>

API実行結果はsendメソッド群の引数に与えていた<code>MixiDelegate</code>プロトコルを実装したデリゲートで処理します。
例えば、APIの実行結果をAlertViewで表示するには次のようなデリゲートメソッドを定義したクラスのインスタンスをsendRequest:delegate:メソッドの引数に与えます。

<pre><code>- (void)mixi:(Mixi*)mixi didFinishLoading:(NSString*)data {
    MixiUtilShowMessageTitle(data, ＠"実行結果");
}
</code></pre>

上記以外のデリゲートメソッドについては<code>MixiDelegate</code>のドキュメントを参照してください。

\section mixiアドプログラムAPI

\subsection mixiアドプログラムAPI

mixiアドプログラムiOSアプリ版のAPIを利用することで、mixiアドプログラムをiOSアプリ版mixiアプリに組み込むこと ができます。ここでは、mixiアプリにどのようにmixiアドプログラムiOSアプリ版の機能を実装するかを説明いたします。

\subsection 表示イメージ

mixiアドプログラムiOSアプリ版の機能を利用するには、アプリ上で以下の「mixiアドプログラム専用枠」を表示してください。

専用枠サイズ： 横幅100%×縦37px（縦表示、横表示の場合とも）

専用枠には上記の図の1～3の場所に、リンクが設置されます。なお表示位置と表示内容は変更することができません。

\subsection 制限事項

mixiアドプログラムiOSアプリ版APIは、どなたでもご利用になれます。なお、お支払い対象となるのはmixiにiOSアプリ版mixiアプリのお申し込みいただき、弊社が承認したmixiアプリのみとなります。

\subsection 利用手順

mixiアドプログラムの機能はiOS SDKではMixiADBannerViewクラスで管理されています。mixiアドプログラムを利用するにはInterface Builderを利用して指定された位置にMixiADBannerViewインスタンスを表示するか、MixiADBannerViewインスタンスを画面に表示するコードをプログラム内に含めてください。

複数の画面でMixiADBannerViewを表示する場合は、MixiADBannerViewの共有オブジェクトを利用するといいでしょう。次は共有オブジェクトを利用してMixiADBannerViewを表示する例です。

<pre><code>- (void)loadView {
    [super loadView];
    [[MixiADBannerView sharedView] addOn:self.view]:
}
</code></pre>

デバイスの向きに応じて表示を変える場合はuseOrientationプロパティをYESに設定するか、shouldAutorotateToInterfaceOrientation: メソッド内で明示的に orientation プロパティを設定してください。

<pre><code>― (BOOL)shouldAutorotateToInterfaceOrientation:(UIInterfaceOrientation)interfaceOrientation {
    [MixiADBannerView sharedView].orientation = interfaceOrientation;
}
</code></pre>

\subsection 実装後の申請

アプリケーションの実装が完了した後、Ad Hocビルドしたバイナリをメールに添付し、下記の通りお送り下さい。

- 宛先: contact-mixiapps@mixi.jp
- 件名: 【iOSアプリ版mAPテスト実行ファイル申請】アプリ名/SAP名
- 内容: リリース予定のアプリケーションのAd Hocビルドしたバイナリ（もしメール上のファイルサイズが添付ファイルを含めて10MBを越える場合は、ダウンロード先・方法を指定してください）

なお、Ad Hoc配布先のデバイスとして下記のUDIDを登録してください。

- 978b464c4afe7b6eacb712a36a86ac68f7da5ab6

ファイルを送付後、下記のページからmixiアドプログラムiOSアプリ版にお申し込みください。

http://developer.mixi.co.jp/appli/policies/map/guidelines/

*/
