[Facebook Instant Games] SDK (context)

---

이 글은 PC 버전 TISTORY에 최적화 되어있습니다.

---

context 관련 SDK

현재 게임 컨텍스트에 관련된 함수와 프로퍼티들을 포함함. 

---

getID( )

A unique identifier for the current game context. This represents a specific context that the game is being played in (for example, a particular messenger conversation or facebook post). The identifier will be null if game is being played in a solo context. This function should not be called until FBInstant.startGameAsync has resolved.

Examples

// This function should be called after FBInstant.startGameAsync()
// resolves.
var contextID = FBInstant.context.getID();

Returns string? A unique identifier for the current game context.

---

getType( )

The type of the current game context. POST - A facebook post. THREAD - A messenger thread. GROUP - A facebook group. SOLO - Default context, where the player is the only participant.

This function should not be called until FBInstant.startGameAsync has resolved.

Examples

// This function should be called after FBInstant.startGameAsync()
// resolves.
var contextType = FBInstant.context.getType();

Returns ("POST" | "THREAD" | "GROUP" | "SOLO") Type of the current game context.

---

isSizeBetween( )

This function determines whether the number of participants in the current game context is between a given minimum and maximum, inclusive. If one of the bounds is null only the other bound will be checked against. It will always return the original result for the first call made in a context in a given game play session. Subsequent calls, regardless of arguments, will return the answer to the original query until a context change occurs and the query result is reset.

This function should not be called until FBInstant.startGameAsync has resolved.

This will be null if one or both of the supplied arguments are not valid, if we do not have a size available for the current context, or if the API is called before startGameAsync() resolves.

Parameters

• minSize number? The minimum bound of the context size query.
• minSize number? The maximum bound of the context size query.
• maxSize number?

Examples

console.log(FBInstant.context.isSizeBetween(3, 5)); (Context size = 4)
// {answer: true, minSize: 3, maxSize: 5}

console.log(FBInstant.context.isSizeBetween(5, 7)); (Context size = 4)
// {answer: false, minSize: 5, maxSize: 7}

console.log(FBInstant.context.isSizeBetween(2, 10)); (Context size = 3)
// {answer: true, minSize: 2, maxSize: 10}
console.log(FBInstant.context.isSizeBetween(4, 8)); (Still in same context)
// {answer: true, minSize: 2, maxSize: 10}

console.log(FBInstant.context.isSizeBetween(3, null)); (Context size = 4)
// {answer: true, minSize: 3, maxSize: null}

console.log(FBInstant.context.isSizeBetween(null, 3)); (Context size = 4)
// {answer: false, minSize: null, maxSize: 3}

console.log(FBInstant.context.isSizeBetween("test", 5)); (Context size = 4)
// null

console.log(FBInstant.context.isSizeBetween(0, 100)); (Context size = null)
// null

Returns ContextSizeResponse?

---

chooseAsync( )

플레이어를 위한 context 선택 대화창을 엽니다. 만약 플레이어가 선택 가능한 context를 선택하면 클라이언트는 context로 전환하려고 노력할 것이고 성공하면  resolve를 뿌릴 것 입니다. 반대로 플레이어가 메뉴를 종료하거나, 클라이언트가 새로운 context로 변경에 실패하면 함수가 거부됩니다.

Parameters

• options Object? 컨텍스트에 제공되어야하는 조건을 정하는 객체
• options.filters Array<ContextFilter>? 컨텍스트 제안에 적용할 필터 세트
• options.maxSize number? 제안된 컨텍스트에 포함되어야할 이상적인 최대값
• options.minSize number? 제안된 컨텍스트에 포함되어야할 이상적인 최소값

Examples

<작성자의 계정에서 chooseAsync 한 화면 (게임하기를 눌러서 성공하면 then으로 넘어가게 된다. x누르면 catch로!)>

console.log(FBInstant.context.getID());
// 1122334455
FBInstant.context
  .chooseAsync()
  .then(function() {
    console.log(FBInstant.context.getID());
    // 1234567890
  });

console.log(FBInstant.context.getID());
// 1122334455
FBInstant.context
  .chooseAsync({
    filters: ['NEW_CONTEXT_ONLY'],
    minSize: 3,
  })
  .then(function() {
    console.log(FBInstant.context.getID());
    // 1234567890
  });

• Throws INVALID_PARAM
• Throws SAME_CONTEXT
• Throws NETWORK_FAILURE
• Throws USER_INPUT
• Throws PENDING_REQUEST
• Throws CLIENT_UNSUPPORTED_OPERATION

Returns Promise 

---

createAsync( )

지정된 플레이어와 현재 플레이어 간 컨텍스트를 만들거나 전환하려고 시도. 나열된 플레이어가 현재 플레이어의 연결된 플레이어가 아니거나, 해당 플레이어가 새로운 컨텍스트로 변경하는 권한을 제공하지 않은 경우 Promise는 reject 됩니다. 그렇지 않고 컨텍스트가 변경되면 resolve 됩니다.

Parameters

• playerID string 플레이어 ID (컨텍스트 ID 아님)

Examples

console.log(FBInstant.context.getID());
// 1122334455
FBInstant.context
  .createAsync('12345678')
  .then(function() {
    console.log(FBInstant.context.getID());
    // 5544332211
  });

• Throws INVALID_PARAM
• Throws SAME_CONTEXT
• Throws NETWORK_FAILURE
• Throws USER_INPUT
• Throws PENDING_REQUEST
• Throws CLIENT_UNSUPPORTED_OPERATION

Returns Promise 

---

switchAsync( )

특정 컨텍스트로의 전환을 요청. 플레이어가 새로운 컨텍스트로 변경하는 권한을 제공하지 않은 경우 Promise는 reject 됩니다. 그렇지 않고 컨텍스트가 변경되면 resolve 됩니다.

Parameters

• id string 원하는 컨텍스트 ID

Examples

console.log(FBInstant.context.getID());
// 1122334455
FBInstant.context
  .switchAsync('1234567890')
  .then(function() {
    console.log(FBInstant.context.getID());
    // 1234567890
  });

• Throws INVALID_PARAM
• Throws SAME_CONTEXT
• Throws NETWORK_FAILURE
• Throws USER_INPUT
• Throws PENDING_REQUEST
• Throws CLIENT_UNSUPPORTED_OPERATION

Returns Promise 

---

ContextPlayer

현재 플레이어가 플레이하고있는 컨텍스트에 있는 플레이어 정보를 나타냅니다.

---

getPlayersAsync( )

활성 플레이어(지난 90일간 현재 컨텍스트에서 플레이했던 사람들)에 대한 정보를 담고 있는 #contextplayer 객체의 배열을 가져옴. 여기엔 현재 플레이어가 포함될 수 있음.

Examples

var contextPlayers = FBInstant.context.getPlayersAsync()
  .then(function(players) {
    console.log(players.map(function(player) {
      return {
        id: player.getID(),
        name: player.getName(),
      }
    }));
  });
// [{id: '123456789', name: 'Luke'}, {id: '987654321', name: 'Leia'}]

• Throws NETWORK_FAILURE
• Throws CLIENT_UNSUPPORTED_OPERATION
• Throws INVALID_OPERATION

Returns Promise<Array<ContextPlayer>>

---

updateAsync( )

페이스북에게 게임에서 일어난 업데이트에 대해서 알려줍니다. 이것을 일시적으로 게임에서 페이스북으로 제어를 양도합니다. 그리고 페이스북에서 업데이트에 대해서 결정을 하게합니다. 페이스북의 결정이 완료되면 resolve나 reject로 반환해주며 제어를 게임으로 다시 넘겨줍니다.

Parameters

• payload UpdatePayload 업데이트를 설명하는 페이로드.

Examples

// 커스텀 업데이트를 보낼겁니다. 만약 플레이어가 메신저 챗 스레드 안에서 플레이한다면,
// 이 메소드는 명시된 이미지와 텍스트로 이루어진 메시지를 보낼 것 입니다.
// 그리고 만약 사람들이 이 메시지로 실행하게 된다면, 그 게임 세션들은 
// FBInstant.getEntryPointData()를 통해 명시된 데이터의 blob을 접근할 수 있을 것입니다.
FBInstant.updateAsync({
  action: 'CUSTOM',
  cta: 'Play',
  image: base64Picture,
  text: {
    default: 'Edgar played their move',
    localizations: {
      en_US: 'Edgar played their move',
      es_LA: '\u00A1Edgar jug\u00F3 su jugada!'
    }
  }
  template: 'play_turn',
  data: { myReplayData: '...' },
  strategy: 'IMMEDIATE',
  notification: 'NO_PUSH'
}).then(function() {
  // closes the game after the update is posted.
  FBInstant.quit();
});

• Throws INVALID_PARAM
• Throws PENDING_REQUEST
• Throws INVALID_OPERATION

Returns Promise (프로미스는 페북의 제어가 끝나면 resolve할 것입니다.)

---

CustomUpdatePayload

FBInstant.updateAsync에 사용. 현지화 된 콘텐츠가 제공되지 않으면 Facebook에서 액션과 문자열을 호출하기 위해 현지화된 로컬라이징을 지원한다.

default 문자열은 항상 영어로해야한다.

Type : Object

Properties

• action UpdateAction 사용자 정의 업데이트의 경우 'CUSTOM'이어야 함.
• template string 이 사용자 지정 업데이트에서 사용중인 템플릿의 문자열 ID입니다. 템플릿은 fbapp-config.json에서 미리 정의해야합니다. fbapp-config.json에 대한 문서는 https://developers.facebook.com/docs/games/instant-games/bundle-config 를 참조하십시오.
• cta

   ( string ? | LocalizableContent ?) call-to-action 버튼입니다. 기본적으로 지역화 된 'Play'를 버튼 텍스트로 사용합니다. call to action 버튼에 현지화 된 문자열을 제공하고 싶으면 cta 값을 'default'로 객체를 전달하고, 다른 객체 매핑 로케일을 'localizations'로 생성해 전달하세요. 

• image string base64로 인코딩 된 이미지의 데이터 URL입니다.
• text ( String | LocalizableContent ) 텍스트 메시지 또는 'default'값으로 기본 텍스트가 있는 객체거나, 현지화 시킨 텍스트들이 들어 있는 'localizations' 객체를 포함

text: {
    default: 'Edgar played their move',
    localizations: {
      en_US: 'Edgar played their move',
      es_LA: '\u00A1Edgar jug\u00F3 su jugada!'
    }
  }

• data 개체 ? 업데이트에 첨부 할 데이터 묶음. 업데이트에서 실행 된 모든 게임 세션은 FBInstant.getEntryPointData()를 통해 이 BLOB에 액세스 할 수 있습니다. 문자열을 지정할 때 1000 자 이하여야합니다.
• strategy 문자열 ? 업데이트를 전달하는 방법을 지정합니다. 다음 중 하나 일 수 있습니다. 'IMMEDIATE'- 업데이트를 즉시 전달해야합니다. 'LAST' 게임 세션이 끝나면 업데이트를 전달해야합니다. 'LAST' 전략을 사용하여 가장 최근 업데이트가 전송됨. 'IMMEDIATE_CLEAR' 업데이트가 즉시 게시되고 보류중인 다른 업데이트 (예 : 'LAST' 전략으로 전송 된 업데이트)가 삭제됩니다. 전략을 지정하지 않으면 기본값은 'IMMEDIATE'입니다.
• notification 문자열 ? 사용자 지정 업데이트에 대한 알림 설정을 지정합니다. 'NO_PUSH'또는 'PUSH'일 수 있으며 기본값은 'NO_PUSH'입니다. push 알림은 중요도가 굉장히 높고 즉시 적용가능한 업데이트만 사용하세요. 또한 푸시 알림은 사용자 설정 및 플랫폼 정책에 따라 항상 보장되는 것은 아닙니다.

---

---