게임 요청

게임 요청 기능은 게이머에게 게임을 함께 할 친구를 초대하는 메커니즘을 제공합니다. 게이머는 한 명 이상의 친구에게 요청을 보내며, 항상 게임과 관련된 행동 유도를 수반합니다. 받는 사람은 기존 게이머 또는 신규 게이머일 수 있습니다.

게임 요청 기능을 사용하여 새로운 게이머를 유치하거나 기존 게이머를 다시 참여시킬 수 있습니다. 다음 2가지 시나리오로 요청을 보낼 수 있습니다.

1. 받는 사람은 보내는 사람의 친구이며 게임을 인증하지 않았습니다. 이 시나리오는 초대에 유용합니다.
2. 받는 사람은 보내는 사람의 친구이며 이전에 게임을 인증했습니다. 이 시나리오는 턴제 알림 및 도움 요청에 유용한 시나리오입니다.

받는 사람은 게임 중인 사람이 보내는 요청을 받으며 Facebook의 여러 위치에서 요청을 확인할 수 있습니다. 요청은 항상 비공개로 전송되므로 받는 사람만 볼 수 있습니다. 단일 요청을 한 번에 여러 받는 사람에게 보낼 수 있지만 요청을 받는 사람은 보내는 사람의 상세 정보만 볼 수 있고 요청을 받는 다른 사람은 알 수 없습니다.

데스크톱용 Facebook에 표시되는 게임 요청 예시

게임 요청은 Facebook 게임과 iOS 및 Android용 모바일 게임에서 사용할 수 있습니다. Facebook 데스크톱 사이트에서는 요청이 필터링되지 않은 경우 알림 아이콘뿐 아니라 화면 왼쪽 아래에 알림 팝업으로도 표시됩니다. 모바일 플랫폼에서 요청은 필터링되지 않은 경우 Facebook 앱의 알림 리스트에 표시됩니다. 요청 데이터는 게임 요청 API를 통해 사용할 수 있고 맞춤 UI는 모바일 게임 내에 더욱 밀접하게 통합된 환경을 위해서만 빌드될 수 있습니다. 그러므로 플랫폼에 상관없이 요청을 구현하고 일관된 사용자 환경을 제공해야 합니다. 하지만 게이머가 보낸 초대는 게임에서 지원하는 모든 플랫폼에 표시됩니다.

요청 대화 상자 실행

게임 요청 대화 상자는 JavaScript, iOS, Android 및 Unity SDK를 통해 생성됩니다. 다음 예시에서는 보내는 사람이 이미 앱을 인증했다고 가정합니다. 요청을 받는 사람이 지정되지 않으면 친구 리스트를 50명 이하로 제한하여 필터링할 수 있으며 등록된 게이머나 등록되지 않은 게이머별로 분류할 수 있습니다. 이는 게임의 재참여 또는 신규 초대를 위한 개별 플로를 제공하는 데 유용합니다.

JavaScript

게임 요청 대화 상자에서 제공한 친구 선택 도구를 사용하여 요청 보내기 예시:

FB.ui({method: 'apprequests',
  message: 'YOUR_MESSAGE_HERE'
}, function(response){
  console.log(response);
});

대화 상자가 닫히면 response 개체에는 request ID와 to 받는 사람 배열 등의 보내기 결과가 포함됩니다. 예를 들면 다음과 같습니다.

{
  "request":"1428237347457728",
  "to":["10150002163885335"]
}

기본적으로 보내는 사람에게 친구 선택 도구가 표시되므로 최대 50명의 받는 사람을 선택할 수 있습니다.

지정된 받는 사람에게 요청 보내기 예시:

FB.ui({method: 'apprequests',
  message: 'YOUR_MESSAGE_HERE',
  to: 'USER_ID'
}, function(response){
  console.log(response);
});

to 필드가 지정된 경우 보내는 사람이 추가로 받는 사람을 선택할 수 없습니다.

지정된 여러 명의 받는 사람에게 요청 보내기 예시:

FB.ui({method: 'apprequests',
  message: 'YOUR_MESSAGE_HERE',
  to: 'USER_ID, USER_ID, USER_ID'
}, function(response){
  console.log(response);
});

여러 받는 사람은 사용자 ID를 쉼표로 구분하는 리스트를 작성하여 지정할 수 있습니다.

특정 친구 리스트에 요청 보내기 예시:

FB.ui({method: 'apprequests',
  message: 'Friend Smash Request!',
  filters: [{name:'GROUP_1_NAME', user_ids:['USER_ID','USER_ID','USER_ID']},{name:'GROUP_2_NAME', user_ids: ['USER_ID','USER_ID','USER_ID']}]
}, function(response){
  console.log(response);
}});

명시적으로 action_type 및 object_id를 표시하여 요청을 통해 개체 보내기 예시:

FB.ui({method: 'apprequests',
  message: 'Take this bomb to blast your way to victory!',
  to: {user-ids},
  action_type:'send',
  object_id: 'YOUR_OBJECT_ID'  // e.g. '191181717736427'
}, function(response){
  console.log(response);
});

턴제 요청의 경우 object_id를 지정하지 마세요.

FB.ui({method: 'apprequests',
  message: 'Just smashed you 78 times! It\'s your turn.',
  to: {user-ids},
  action_type:'turn'
}, function(response){
  console.log(response);
});

또는 받는 사람을 이름이 지정된 리스트로 구분하여 게이머가 게임 내 받는 사람의 등록 여부에 따라 논리적으로 그룹화된 친구 중에서 선택할 수 있습니다.

자세한 내용은 JavaScript용 Facebook SDK의 FB.ui 참조 문서를 확인하세요.

iOS SDK

iOS SDK에서 제공하는 친구 선택 도구를 사용하여 요청 대화 상자 실행 예시:

FBSDKGameRequestContent *gameRequestContent = [[FBSDKGameRequestContent alloc] init];
// Look at FBSDKGameRequestContent for futher optional properties
gameRequestContent.message = @"YOUR_MESSAGE_HERE";
gameRequestContent.title = @"OPTIONAL TITLE";

// Assuming self implements <FBSDKGameRequestDialogDelegate>
[FBSDKGameRequestDialog showWithContent:gameRequestContent delegate:self];

iOS SDK를 통해 action_type 및 object_id를 명시적으로 표시하여 특정 받는 사람에게 요청 보내기 예시:

FBSDKGameRequestContent *gameRequestContent = [[FBSDKGameRequestContent alloc] init];
gameRequestContent.message = @"Take this bomb to blast your way to victory!";
gameRequestContent.to = @[@"RECIPIENT_USER_ID"];
gameRequestContent.objectID = @"YOUR_OBJECT_ID";
gameRequestContent.actionType = @"ACTION_TYPE";

// Assuming self implements <FBSDKGameRequestDialogDelegate>
[FBSDKGameRequestDialog showWithContent:gameRequestContent delegate:self];

Android SDK

Android SDK를 통해 요청 대화 상자 친구 선택 도구를 사용하여 요청 보내기 예시:

GameRequestDialog requestDialog;
CallbackManager callbackManager;

public void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  FacebookSdk.sdkInitialize(this.getApplicationContext());
  callbackManager = CallbackManager.Factory.create();
  requestDialog = new GameRequestDialog(this);
  requestDialog.registerCallback(callbackManager,
    new FacebookCallback<GameRequestDialog.Result>() {
    public void onSuccess(GameRequestDialog.Result result) {
      String id = result.getId();
    }
    public void onCancel() {}
      public void onError(FacebookException error) {}
    }
  );
}

private void onClickRequestButton() {
  GameRequestContent content = new GameRequestContent.Builder()
    .setMessage("Come play this level with me")
    .build();
  requestDialog.show(content);
}

protected void onActivityResult(int requestCode, int resultCode, Intent data) {
  super.onActivityResult(requestCode, resultCode, data);
  callbackManager.onActivityResult(requestCode, resultCode, data);
}

Android SDK를 통해 액션과 개체를 명시적으로 표시하여 요청 보내기 예시:

private void onClickRequestButton() {
  GameRequestContent content = new GameRequestContent.Builder()
    .setMessage("Come play this level with me")
    .setTo("USER_ID")
    .setActionType(ActionType.SEND)
    .setObjectId("YOUR_OBJECT_ID")
    .build();
  requestDialog.show(content);
}

Unity SDK

다음은 Unity SDK에서 요청이 수행되는 방식입니다. 자세한 내용은 FB.AppRequest 문서를 참조하세요.

FB.AppRequest(
  message: "I Just got " + GameStateManager.Score.ToString() + " points! Can you beat it?",
  to: recipients,
  data: "{\"challenge_score\":" + GameStateManager.Score.ToString() + "}"
  title: "Friend Smash Challenge!",
  callback:appRequestCallback
);

대화 상자 매개변수

게임 요청 대화 상자는 해당 동작을 판별하는 여러 추가 매개변수를 사용하여 만들 수 있습니다. 이러한 매개변수는 아래에 설명되어 있습니다.

응답 데이터

게임 요청 대화 상자를 통해 요청을 보내면 다음 정보를 포함하는 콜백에 응답이 전달됩니다.

게임 내 요청 처리

요청 승인

받는 사람이 Facebook 데스크톱 사이트에서 요청을 승인하면 요청을 보낸 게임의 URL로 전송됩니다. 이 URL에는 사용자가 승인하는 쉼표로 구분된 요청 ID 리스트인 추가 GET 매개변수 request_ids가 포함됩니다.

http://apps.facebook.com/[app_name]/?request_ids=[REQUEST_IDs]

받는 사람이 요청을 승인해도 요청은 자동으로 삭제되지 않습니다. 이는 게임에서 삭제해야 합니다. 게임을 실행할 때 그래프 API에서 해당 사용자의 미해결 요청 리스트를 읽고 처리 후 각 요청을 삭제하는 것이 일반적인 접근 방법입니다.

받는 사람이 모바일 플랫폼에서 요청을 수락하면 앱에 딥 링크됩니다. 앱을 읽어들일 때 추가 매개변수는 요청 ID를 나타냅니다. 요청을 승인하고 지우는 책임은 모바일에도 적용됩니다. 게임 실행 시 보류 중인 요청을 확인하고 지우는 것이 좋습니다.

요청 읽기

보낸 요청마다 고유한 요청 개체 ID가 있습니다. 이 ID는 요청 개체를 나타냅니다. 이 요청 개체 ID는 받는 사람 사용자 ID와 결합하여 특정 요청 인스턴스를 만들 수 있습니다. 요청의 인스턴스 하나를 나타내는 것으로, 이 요청은 특정 받는 사람에게 전송된 것입니다.

예를 들어 요청을 보낼 때 게임 요청 대화 상자의 응답은 다음과 같습니다.

{
  request: 'REQUEST_OBJECT_ID'
  to:[array of USER_IDs]
}

그래프 API를 통해 요청 개체 ID를 검색하는 경우 수신되는 응답은 검색의 컨텍스트 보기에 따라 달라지지만, 응답은 항상 전체 요청 개체를 나타냅니다.

예를 들어 받는 사람의 사용자 액세스 토큰을 사용하여 http://graph.facebook.com/{REQUEST_OBJECT_ID}?access_token=USER_ACCESS_TOKEN을 쿼리하면 다음 응답이 표시됩니다.

{
  "id": "REQUEST_OBJECT_ID",
  "application": {
    "name": "APP_DISPLAY_NAME",
    "namespace": "APP_NAMESPACE",
    "id": "APP_ID"
  },
  "to": {
    "name": "RECIPIENT_FULL_NAME",
    "id": "RECIPIENT_USER_ID"
  },
  "from": {
    "name": "SENDER_FULL_NAME",
    "id": "SENDER_USER_ID"
  },
  "message": "ATTACHED_MESSAGE",
  "created_time": "2014-01-17T16:39:00+0000"
}

to와 from 필드가 둘 다 반환됩니다. 그러나 보내는 사람의 액세스 토큰 또는 앱 액세스 토큰을 사용하여 동일한 엔드포인트를 호출하면 Facebook이 다음을 반환합니다.

{
  "id": "REQUEST_OBJECT_ID",
  "application": {
    "name": "APP_DISPLAY_NAME",
    "namespace": "APP_NAMESPACE",
    "id": "APP_ID"
  },
  "from": {
    "name": "SENDER_FULL_NAME",
    "id": "SENDER_USER_ID"
  },
  "message": "ATTACHED_MESSAGE",
  "created_time": "2014-01-17T16:39:00+0000"
}

앱 액세스 토큰을 사용하여 받는 사람을 포함하는 전체 요청을 가져오려면 밑줄('_') 문자 뒤에 받는 사람 사용자 ID를 추가해야 합니다. 예를 들어 https://graph.facebook.com/{REQUEST_OBJECT_ID}_{USER_ID}?access_token={APP_ACCESS_TOKEN}을 호출하면 다음이 반환됩니다.

{
  "id": "REQUEST_OBJECT_ID",
  "application": {
    "name": "APP_DISPLAY_NAME",
    "namespace": "APP_NAMESPACE",
    "id": "APP_ID"
  },
  "to": {
    "name": "RECIPIENT_FULL_NAME",
    "id": "RECIPIENT_USER_ID"
  },
  "from": {
    "name": "SENDER_FULL_NAME",
    "id": "SENDER_USER_ID"
  },
  "message": "ATTACHED_MESSAGE",
  "created_time": "2014-01-17T16:39:00+0000"
}

모든 요청 읽기

받는 사람의 요청을 모두 읽으려면 받는 사람의 USER ACCESS TOKEN을 사용하여 다음과 같이 그래프를 쿼리할 수 있습니다. 그러면 앱에서 해당 사용자의 요청 ID 리스트를 반환합니다.

GET https://graph.facebook.com/me/apprequests?access_token=[USER ACCESS TOKEN]

요청 삭제

받는 사람이 요청을 승인한 후에도 게임 요청은 자동으로 삭제되지 않습니다. 요청이 승인되고 나면 개발자가 요청을 삭제해야 합니다. 요청이 승인되고 나면 게이머 대신 요청을 삭제해야 합니다.

다음과 같은 방법으로 요청을 삭제할 수 있습니다.

그래프 API

다음과 같이 연결된 request_id에 HTTP DELETE 요청을 발행하세요.

DELETE https://graph.facebook.com/[{REQUEST_OBJECT_ID}_{USER_ID}]?
      access_token=[USER or APP ACCESS TOKEN]

JavaScript

function deleteRequest(requestId) {
  FB.api(requestId, 'delete', function(response) {
    console.log(response);
  });
}

리퍼럴 및 보상 요청 추적

결과적으로 요청을 받는 사람이 수행하는 액션에 따라 게임 요청을 보내는 사람에게 보상할 수 있습니다. 예를 들어 요청을 보내기만 하는 게이머에게는 보상할 수 없습니다. 요청을 받는 사람이 요청을 승인한 결과로 게임을 설치하고 특정 레벨에 도달하면 보내는 사람에게 보상할 수 있습니다.

보내는 사람에게 보상하려면 누가 보상받을지 알아야 합니다. 다음의 두 가지 방법으로 이 작업을 수행할 수 있습니다.

1. 요청을 보낼 때 게임 요청 대화 상자의 응답에 반환된 request_id를 저장하고 요청이 수신될 때 ID와 일치하면 보내는 사람에게 보상합니다.
2. 요청을 받는 사람이 게임을 실행한 경우 게이머의 모든 요청을 읽고 해당 요청의 from 필드에 있는 id를 기반으로 보내는 사람에게 보상합니다. 여러 친구가 한 게이머를 초대한 경우 첫 번째로 보내는 사람에게 보상할지 또는 보내는 사람 모두에게 보상할지 선택할 수 있습니다.

초대 가능한 친구 API

현지화

Facebook에서는 전 세계 타겟에게 최상의 사용자 환경을 제공하는 데 도움이 되도록 requests 현지화를 지원합니다. 요청을 번역하기 전에 다른 유형의 요청과 해당 요청을 표시하는 방법을 아는 것이 중요합니다. 요청은 'Anita sent you a request'(Anita 님이 요청을 전송했습니다)와 같은 표준 양식으로 표시되거나, 액션/개체 쌍이 지정된 경우 'Anita asked you for a Life'(Anita 님이 라이프를 요청하셨습니다) 또는 'Anita sent you a Bomb'(Anita 님이 폭탄을 보냈습니다)으로 표시될 수 있습니다. 친구를 상대로 하는 게임에서 차례가 되었음을 알리는 턴 요청도 있습니다. 이러한 예시는 모두 게임을 승인한 게이머에게 표시됩니다. 받는 사람이 게임을 설치하지 않은 경우 초대 양식으로 요청이 표시됩니다. 예를 들어 'Anita invited you to play Friend Smash!'(Anita 님이 Friend Smash!에 초대하셨습니다)가 표시됩니다. 각 요청을 번역하는 방법에 대해 살펴보겠습니다.

초대 번역

초대 텍스트는 Facebook에서 자동으로 번역하므로 개발자가 제어할 수 없습니다. 받는 사람이 설정한 기본 언어로 번역됩니다.

초대 알림(영어)

초대 알림(태국어)

위의 예에서 'invited you to play'라는 텍스트가 다른 언어(예시에서는 태국어)로 자동 번역됩니다. 앱 이름과 설명은 앱 설정의 '현지화' 섹션에서 아래 노란색 상자에 '표시 이름'과 '설명'으로 번역됩니다.

앱의 표시 이름 및 설명 번역

요청은 앱 센터에도 표시될 수 있습니다. 앱 센터에는 요청 '메시지'가 표시됩니다. 메시지는 개발자가 번역할 수 있습니다. 아래 예시에서 메시지가 영어로는 'Can I have a life to help me through the next level?'이고, 태국어로는 'ช่วยส่งตัวเพิ่มให้หน่อย ต้องใช้ไปเลเวลหน้า'입니다. 현재는 요청의 기본 텍스트인 'Anita sent you a request'가 앱 센터에 표시되지 않습니다.

앱 센터 요청(영어)

앱 센터 요청(태국어)

메시지 번역

요청 대화 상자를 호출할 때 메시지를 매개변수로 전달하므로 요청 대화 상자를 호출하고 번역된 문자열을 메시지로 전달하기 전에 직접 번역할 수 있습니다. 번역을 동적으로 변경하려면 대화 상자를 호출하기 전에 수행해야 합니다. 요청 미리 보기에서 보내는 사람에게 표시되고 받는 사람이 요청을 받을 때 표시되는 텍스트와 동일하므로 표시할 언어는 개발자가 결정합니다.

많은 개발자가 보내는 사람의 언어를 감지한 다음 이를 통해 메시지에 사용할 언어를 판단합니다. 대부분의 경우 보내는 사람과 받는 사람은 동일한 언어를 사용한다고 가정합니다. 위의 예에서 보내는 사람의 언어를 확인한 후 언어가 태국어이면 다음과 같이 태국어로 된 문자열을 메시지로 직접 보낼 수 있습니다.

FB.ui({method: 'apprequests',
  message: 'ช่วยส่งตัวเพิ่มให้หน่อย ต้องใช้ไปเลเวลหน้า'
}, requestCallback);

모범 사례

요청에 데이터 추가

위의 대화 상자 매개변수 섹션에 언급한 대로, 요청과 함께 보낼 데이터를 최대 255자 추가할 수 있습니다. 이 기능을 사용하여 요청에 대한 추가 정보를 전송하거나 나중에 서버에 저장된 관련 정보를 검색하는 데 사용할 수 있는 식별자를 추가할 수 있습니다.

예를 들어 Facebook 샘플 게임 프로젝트인 Friend Smash에서 게이머는 돌아가며 가능한 가장 많은 수의 친구를 '이기기' 위해 경쟁합니다. 한 게이머가 요청을 통해 다른 게이머에게 도전장을 보내면 데이터 매개변수를 사용하여 도전하는 게이머의 최신 점수를 저장합니다. 그러면 게임에서 수신 게이머에 대해 이 값을 추출하여 다음 게임의 타겟 점수로 만듭니다.

초대 필터

맞춤 친구 선택 도구를 빌드하거나 요청을 보낼 사용자를 선택할 때 게이머가 원하는 상대를 받는 사람으로 선택하는 데 도움이 될 필터를 제공하세요.

게임 요청 대화 상자를 사용하여 초대를 구현할 때 사용되는 일반적인 필터는 app_non_users 필터입니다. 이 필터를 사용하면 게임 요청 대화 상자가 이전에 게임을 한 사용자를 표시하지 않습니다. 또 다른 필터로는 최근에 교류한 게이머 또는 개발자가 관리하는 비슷한 게임의 게이머를 고려할 수 있습니다. 사용 가능한 전체 필터 리스트는 게임 요청 대화 상자 - 매개변수 참조 문서를 참조하세요.

참여를 유도하는 메커니즘 만들기

게이머가 게임에서 친구를 방문하거나 친구와 직접 교류할 때 참여를 유도하는 메커니즘을 만듭니다. 예를 들어 게임에서 이웃의 개념을 지원하는 경우 게이머가 이웃의 환경을 방문할 때 보너스 에너지를 부여합니다. 게이머의 기지가 공격을 당하면 친구가 수리할 수 있게 합니다. 일반적으로 게이머는 친구의 진행을 지원하는 데 가치를 느끼므로, 게이머에게 이러한 기회를 제공하면 소셜 환경이 향상되며 게임하는 사람이 증가하게 됩니다.

게이머에게 가치 있는 개체 만들기

게임 이용 또는 소셜 환경을 향상시키는 데 사용할 수 있는 게이머에게 가치 있는 아이템을 제공합니다.

게이머를 세분화하고 컨텍스트에 맞는 요청 제공

게이머를 평가하고 게임에 적합한 다양한 그룹으로 구분합니다(예: 새로운 게이머, 만들기 취미가 있는 게이머, 친구가 많은 게이머, 참여하는 게이머 등). 게이머 입장에서 어떤 유형의 그룹이 유용한지 생각해 보고 그룹별로 적합한 아이템을 제공합니다.