UDN
Search public documentation:

FacebookIntegrationJP
English Translation
中国翻译
한국어

Interested in the Unreal Engine?
Visit the Unreal Technology site.

Looking for jobs and company info?
Check out the Epic games site.

Questions about support via UDN?
Contact the UDN Staff

UE3 ホーム > PlatformInterface フレームワーク > Facebook インテグレーション

Facebook インテグレーション


ALERT! このドキュメントでは、2011年9月のビルドで追加された機能およびシステムについて解説しています。これより前のバージョンにも Facebook 機能がついていますが、実装が異なります。

概要


Facebook インテグレーションによって、「Unreal Engine 3」で作成されるゲームに、ソーシャル機能を付加させることができるようになります。

注意 : Facebook インテグレーション機能は、現在のところ、iOS プラットフォーム上で稼働するゲームに限られています。

FacebookIntegration


FacebookIntegration クラスは、Facebook に接続しインタラクトするための機能を含む基本クラスです。 CloudStorageBase クラスは、 PlatformInterfaceBase クラスを継承しており、このクラスに含まれているデリゲートシステムを利用します。各プラットフォーム (PC、iOS 他) には、 FacebookIntegration クラスを拡張したサブクラスがあり、それによって各プラットフォームに特有な実装が可能となります。

プロパティ

  • AppID - ゲームをリンクさせる Facebook アプリケーションの ID です。これを入手するには、 Facebook の開発者用サイト でアプリケーションをセットアップします。ゲームはそれぞれ、 DefaultEngine.ini コンフィグ ファイルでこの値を指定する必要があります。
  • Username - 認証プロセス (authorization process) によって取得されたプレイヤーのユーザー名を保持します。
  • UserID - 認証プロセスによって取得されたプレイヤーの Facebook ID を保持します。
  • AccessToken - 認証プロセスによって取得されたプレイヤーのアクセストークンを保持します。
  • FriendsList - プレイヤーの friend (友人) りストを保持する FacebookFriends の配列です。
    • Name - friend の表示名です。
    • Id - friend の Facebook ユーザー ID です。

関数

  • Init - Facebook インテグレーションを初期化するためにエンジンによって呼び出されるイベントです。
  • Authorize - プレイヤーの Facebook 情報にゲームがアクセスできるようにするプロセスを開始します。Facebook アプリケーションを認証するようにプレイヤーに対して要求します。
  • IsAuthorized - アプリケーションがプレイヤーによって認証されたか否かを返します。
  • WebRequest [URL] [Verb] [Payload] [Tag] [bRetrieveHeaders] [bForceBinaryResponse] - 指定されたデータをともなって、指定の URL に一般的 WEB リクエストを送信します。レスポンスは、 FID_WebRequestComplete デリゲートの呼び出しを介して戻ってきます。
    • URL - リクエストのための URL です。http または https (現在のプラットフォームが https の送信をサポートしている場合) にすることができます。
    • Verb - リクエストのタイプ (POST、GET) を指定する文字列です。
    • Payload - ウェブリクエストにおいてペイロードとして送信する文字列 (UTF8) です。
    • bRetrieveHeaders - TRUE の場合は、レスポンスオブジェクトにすべてのヘッダが含まれます。(FALSE の場合は、メモリのチャーン (確保開放の繰り返し) が大幅に削減されます)。
    • bForceBinaryResponce - TRUE の場合は、レスポンスが文字列に変換されずに、バイナリ レスポンス データに格納されます。
  • FacebookRequest [GraphRequest] - Facebook GraphAPI リクエストを送信します。レスポンスは、 FID_FacebookRequestComplete デリゲートの呼び出しを介して戻ってきます。
  • FacebookDialog [Action] [ParamKeysAndValues] - プラットフォームのダイアログを開き、Facebook のアクション (例 : プレイヤーのウォールへの投稿) を実行します。
    • Action - 開くダイアログのタイプです。(例 : feed)。
    • ParamKeysAndvalues - ダイアログに渡す特別なパラメータ (ダイアログ固有) を指定する文字列の配列です。キーと値の区切り : < "key1", "value1", "key2", "value2" >
  • Disconnect - Facebook との接続を切るために呼び出します。次回、認証が実行されると、認証ウェブページが再び表示されます。

デリゲート

EFacebookIntegrationDelegate 列挙型は、コールバックを受け取ることができるデリゲートの型のための ID を定義します。 プラットフォーム インターフェース フレームワーク システムを使用して、デリゲートを各 ID に割り当てることができます。

  • FID_AuthorizationComplete - 認証プロセスのレスポンスを受け取った場合に、当該 ID に割り当てられているデリゲートが実行されます。
    • bSuccessful - TRUE になります。
    • Data - データは含まれていません。
  • FID_FacebookRequestComplete - Facebook GraphAPI リクエストのレスポンスを受け取った場合に、当該 ID に割り当てられているデリゲートが実行されます。
    • bSuccessful - TRUE になります。
    • Data - GraphAPI リクエストのレスポンス文字列を含みます。
  • FID_WebRequestComplete - web リクエストのレスポンスを受け取った場合に、当該 ID に割り当てられているデリゲートが実行されます。
    • bSuccessful - TRUE になります。
    • Data - web リクエストのレスポンス文字列を含みます。
  • FID_DialogComplete - web リクエストのレスポンスを受け取った場合に、当該 ID に割り当てられているデリゲートが実行されます。
    • bSuccessful - TRUE の場合は、ダイアログが成功しました。そうでない場合は、ダイアログがキャンセルされたか失敗したかのどちらかです。
    • Data - ダイアログからのレスポンスの文字列があれば、それを含みます。(例 : 復帰 URL、エラーメッセージ)。
  • FID_FriendsListComplete - プレイヤーの friend リストを求めるリクエストによるレスポンスが受け取られた場合に、当該 ID に割り当てられているデリゲートが実行されます。
    • bSuccessful - TRUE の場合は、リクエストが成功しました。
    • Data - データは含まれていません。friend リストは、 FriendsList 配列に保存されます。

実装の詳細


「Unreal Engine 3」の Facebook インテグレーションをセットアップおよび使用する場合、そのワークフローの概略は以下のようになります。

  1. Facebook アプリケーションをまだ作成していない場合は、Facebook の開発者用サイトで作成します。
  2. UDKGameOverrides.plist ファイルに CFBundleURLTypes のエントリーを追加して、Facebook からのコールバックを扱えるようにします。
       <key>CFBundleURLTypes</key>
       <array>
         <dict>
           <key>CFBundleURLSchemes</key>
           <array>
             <string>fb[FacebookAppID]</string>
           </array>
         </dict>
       </array>
       
    [FacebookAppID] は、アプリケーションの ID と置き換えてください。
  3. DefaultEngine.ini ファイルの [FacebookIntegration] セクションにおいて、Facebook アプリケーションの ID を使って AppID プロパティをセットします。
       [FacebookIntegration]
       AppID=[FacebookAppID]
       +Permissions=email
       +Permissions=read_stream
       
    [FacebookAppID] は、アプリケーションの ID と置き換えてください。
  4. FacebookIntegration オブジェクトへの参照を取得します。そのためには、 PlatformInterfaceBase クラスの static GetFacebookIntegration() を呼び出すとともに、認証および web リクエスト、GraphAPI リクエストの各コールバックのためのデリゲートをセットアップします。これは通常、Facebook の機能を配置した場所に応じて、 PostBeginPlay() またはその他の初期化関数において処理されます。
       var FacebookIntegration Facebook;
    
       ...
    
       Facebook = class'PlatformInterfaceBase'.static.GetFacebookIntegration();
       Facebook.AddDelegate(FID_AuthorizationComplete, OnFBAuthComplete);
       Facebook.AddDelegate(FID_FacebookRequestComplete, OnFBRequestComplete);
       Facebook.AddDelegate(FID_WebRequestComplete, OnWebRequestComplete);
       
    OnFBAuthComplete および OnFBRequestCompleteOnWebRequestComplete は、単なる例です。これらの名前は、 PlatformInterfaceDelegate デリゲートのシグネチャと一致する関数の名前にすることができます。
       delegate PlatformInterfaceDelegate(const out PlatformInterfaceDelegateResult Result);
       
  5. ユーザーが Facebook 機能を有効にする場合は、 ユーザーが認証されていないならば (IsAuthroized() を呼び出すことによってチェックする)、 FacebookIntegration 上にある Authorize() を呼び出し、 FID_AuthorizationComplete コールバックを待ちます。
       if (!Facebook.IsAuthorized())
       {
          if (Facebook.Authorize() == true)
          {
             bIsFBAuthenticating = true;
          }
          return;
       }
       
  6. 認証に成功すると、 WebRequest() または FacebookRequest() を利用してリクエストを行い、コールバックデリゲートでリクエストを処理することが可能になります。
       Facebook.FacebookRequest("me/friends");
       

基本的な実装は、 UDKBase\Classes ディレクトリの CloudPC.uc スクリプトに置かれています。また、 CloudGame ゲームタイプを使用してテストすることが可能です。


CloudGame Facebook のより高度な実装例を下に掲載します。Facebook 機能はモバイルのメニュー内に実装されます。2 個のボタンが配置されることによって、ユーザーが Facebook インテグレーションを有効にし、friends (友人) のリストを取得することができるようになります。friends は、スクロールリストに表示され、ここから選択することができます。また、メニューにはステータスバーがあり、実行中のアクションを示すテキスト出力が表示されます。

注意 : 以下の例では、 モバイルメニュー技術ガイド のページの カスタムの入力メニュー例 にあるクラスを使っています。したがって、ここではこれらのクラスについて解説しません。

例は、カスタムのモバイルメニューを表示することから始まります。

fb_menu.jpg

[Facebook] ボタンをタップすると、認証プロセスが開始され、デバイス上の Facebook アプリに切り替わります (アプリがインストールされていない場合は Safari から Facebook サイトに入ります)。

fb_auth.jpg

ユーザーが了承すると、ゲームにリダイレクトされ、ステータスが更新されて認証に成功したことが表示されます。

fb_success.jpg

この時点で [Friends] ボタンをタップすると、ユーザーの friends リストのための GraphAPI リクエストが開始されます。

fb_request.jpg

リクエストが返されると、friends がメニュー内のリストに追加され、次のように表示されます。

fb_friends.jpg

リストがスクロールできるようになり、friends が選択可能になります。

fb_select.jpg

friend が選択されると、リストが閉じられ、選択した friend がメニュー内のステータスバーに表示されるようになります。

fb_status.jpg

モバイルメニュー

SocialMenu.uc
class SocialMenu extends UDNMobileMenuScene;

/** Reference to the Facebook object */
var FacebookIntegration Facebook;

/** Are we currently authenticating with facebook? */
var bool bIsFBAuthenticating;

/** Have we already requested friends (because we don't want to send the request each time we wnt to view them) */
var bool bFriendsListPopulated;

/**
 * Called to initialize the menu and set up the scene
 */
function InitMenuScene(MobilePlayerInput PlayerInput, int ScreenWidth, int ScreenHeight, bool bIsFirstInitialization)
{
   Super.InitMenuScene(PlayerInput, ScreenWidth, ScreenHeight, bIsFirstInitialization);

   //initialize list
    List.InitMenuObject(PlayerInput, self, ScreenWidth, ScreenHeight, bIsFirstInitialization);

      //Get the reference to the Facebook object singleton
   Facebook = class'PlatformInterfaceBase'.static.GetFacebookIntegration();

   //Set the delegates to use for the authorization and GraphAPI request callbacks (we're not using any web requests)
   Facebook.AddDelegate(FID_AuthorizationComplete, OnFBAuthComplete);
   Facebook.AddDelegate(FID_FacebookRequestComplete, OnFBRequestComplete);

   //Set up some delegates for our menu objects (buttons, list, etc.)
   UDNMobileMenuButton(FindMenuObject("Authorize")).OnClick = AuthorizeFacebook;
   UDNMobileMenuButton(FindMenuObject("Friends")).OnClick = RequestFriends;
   List.OnChange = OnSelectFriend;
   List.OnCancel = HideFriendsList;
}

/**
 * Called when the menu is closed to clean up the scene
 */
function bool Closing()
{
   //Clear all the delegates when the menu closes
   Facebook.ClearDelegate(FID_AuthorizationComplete, OnFBAuthComplete);
   Facebook.ClearDelegate(FID_FacebookRequestComplete, OnFBRequestComplete);

   return super.Closing();
}

/**
 * Callback from the "Authorize" button's OnClick delegate - Performs the Facebook authorization process
 *
 * The parameters are not used - they are needed in this case simply because this is matching the OnClick delegate of the UDNMobileMenuButton
 */
function AuthorizeFacebook(UDNMobileMenuObject Sender, float X, float Y)
{
   //have we authorized previously?
   if (!Facebook.IsAuthorized())
   {
      //send for authorization
      UDNMobileMenuLabel(FindMenuObject("Status")).Caption = "Facebook Not Authorized";
      if (Facebook.Authorize() == true)
      {
         UDNMobileMenuLabel(FindMenuObject("Status")).Caption = "Facebook Is Authorizing";
         bIsFBAuthenticating = true;
      }
   }
   else
   {
      //set status as authorized
      UDNMobileMenuLabel(FindMenuObject("Status")).Caption = "Facebook Authorized";
   }
}

/**
 * Callback from the "Friends" button's OnClick delegate - Sends the Facebook GraphAPI request for the user's friends
 *
 * The parameters are not used - they are needed in this case simply because this is matching the OnClick delegate of the UDNMobileMenuButton
 */
function RequestFriends(UDNMobileMenuObject Sender, float X, float Y)
{
   //have we requested friends previously?
   if(!bFriendsListPopulated)
   {
      //send a request to graphAPI for friends list
      UDNMobileMenuLabel(FindMenuObject("Status")).Caption = "Requesting Friends List";
      Facebook.FacebookRequest("me/friends");
   }
   else
   {
      //show the previously populated friends list
      List.bIsHidden = false;
   }
}

/**
 * Callback from the list when an item is selected - Sets the text of the status bar label and closes the list
 *
 * @item - holds the name of the friend that was selected in the list
 */
function OnSelectFriend(int Idx, string Item, float X, float Y)
{
   UDNMobileMenuLabel(FindMenuObject("Status")).Caption = item;
   list.bIsHidden=true;
}

/**
 * Callback from the list when the "cancel" button is tapped - closes the list
 */
function HideFriendsList()
{
   list.bIsHidden=true;
}

/**
 * Callback from Authorize()
 *
 * @Result - Holds the data sent back from the authorization
 */
function OnFBAuthComplete(const out PlatformInterfaceDelegateResult Result)
{
   //set status to reflect successful authorization
   UDNMobileMenuLabel(FindMenuObject("Status")).Caption = "Facebook Auth Complete:"$Result.bSuccessful;
   bIsFBAuthenticating = false;
}

/**
 * Callback from GraphAPI requests
 *
 * @Result - Holds the data sent back from the request
 */
function OnFBRequestComplete(const out PlatformInterfaceDelegateResult Result)
{
   local JsonObject Root, FriendsArray, Friend;
   local int Index;

   if (Result.bSuccessful)
   {
      //set status as successful request
      UDNMobileMenuLabel(FindMenuObject("Status")).Caption = "Facebook Request Successful";

      //get the data from the request
      Root = class'JsonObject'.static.DecodeJson(Result.Data.StringValue);

      // get the friends array - top level is "data" = [friend,friend]
      FriendsArray = Root.GetObject("data");

      //output number of friends to status
      UDNMobileMenuLabel(FindMenuObject("Status")).Caption = "You have " $ FriendsArray.ObjectArray.length $ " friends:";

      // loop over the friends
      for (Index = 0; Index < FriendsArray.ObjectArray.length; Index++)
      {
         // get a friend object
         Friend = FriendsArray.ObjectArray[Index];

         // output friend info
         UDNMobileMenuLabel(FindMenuObject("Status")).Caption = "Friend " $ Friend.GetStringValue("name") $ " has ID " $ Friend.GetStringValue("id");

         //add new friend to the list
         List.AddItem(Friend.GetStringValue("name"));
      }

      //display the list
      List.bIsHidden = false;
      bFriendsListPopulated = true;
   }
   else
   {
      //set status as unsuccessful request
      UDNMobileMenuLabel(FindMenuObject("Status")).Caption = "Facebook Request Unsuccessful";
   }
}

defaultproperties
{
   //Authorize button
   Begin Object Class=UDNMobileMenuButton Name=AuthorizeButton
      Tag="Authorize"
      Left=20
      Top=10
      Width=128
      Height=32
      TopLeeway=20
      Images(0)=Texture2D'PlatformInterfaceContent.fb_label'
        Images(1)=Texture2D'PlatformInterfaceContent.fb_label'
         ImagesUVs(0)=(bCustomCoords=true,U=0,V=0,UL=128,VL=32)
         ImagesUVs(1)=(bCustomCoords=true,U=0,V=0,UL=128,VL=32)
   End Object
   MenuObjects.Add(AuthorizeButton)

   //Friends button
   Begin Object Class=UDNMobileMenuButton Name=FriendsButton
      Tag="Friends"
      Left=20
      Top=52
      Width=128
      Height=32
      TopLeeway=20
      TextFont=Font'EngineFonts.SmallFont'
      Images(0)=Texture2D'PlatformInterfaceContent.fb_friends'
        Images(1)=Texture2D'PlatformInterfaceContent.fb_friends'
         ImagesUVs(0)=(bCustomCoords=true,U=0,V=0,UL=128,VL=32)
         ImagesUVs(1)=(bCustomCoords=true,U=0,V=0,UL=128,VL=32)
   End Object
   MenuObjects.Add(FriendsButton)

   //Status bar label
    Begin Object class=UDNMobileMenuLabel name=Label0
      Tag="Status"
      Height=32
      Width=480
      Left=0
      Top=288
      TextFont=Font'EngineFonts.SmallFont'
      BackgroundColors(0)=(R=0.0,G=0.0,B=0.0,A=1.0)
      BackgroundColors(1)=(R=0.0,G=0.0,B=0.0,A=1.0)
      CaptionColors(0)=(R=1.0,G=1.0,B=1.0,A=1.0)
      CaptionColors(1)=(R=1.0,G=1.0,B=1.0,A=1.0)
      Caption="Status"
   End Object
   MenuObjects.Add(Label0)

   //Friends list
   Begin Object class=UDNMobileMenuList name=List0
      Tag="FriendsList"
      bIsHidden=true
      bHasCancel=true
      Title="Friends"
   End Object
   List=List0
}

PlayerController

SocialPC.uc
class SocialPC extends SimplePC;

event InitInputSystem()
{
   Super.InitInputSystem();

   MPI.OpenMenuScene(class'SocialMenu');
}

defaultproperties
{
   InputClass=class'GameFramework.MobilePlayerInput'
}

Gametype

SocialGame.uc
class SocialGame extends SimpleGame;

defaultproperties
{
   PlayerControllerClass=class'UDNGame.SocialPC'
}