Permintaan Game

Permintaan game memberikan mekanisme kepada pemain untuk mengundang teman mereka bermain game. Permintaan dikirimkan oleh pemain ke salah satu atau beberapa teman dan selalu berisi ajakan-bertindak untuk game tersebut. Penerima dapat berupa pemain yang sudah ada atau pemain baru.

Permintaan game dapat digunakan untuk menarik perhatian pemain baru atau berinteraksi kembali dengan pemain yang sudah ada. Permintaan dapat dikirim dalam dua skenario:

1. Penerima adalah teman pengirim dan belum mengautentikasi game. Skenario ini berguna untuk undangan.
2. Penerima adalah teman pengirim dan sudah mengautentikasi game sebelumnya. Skenario ini berguna untuk notifikasi berbasis giliran dan meminta bantuan.

Permintaan dikirim saat pengirim berada dalam game dan ditampilkan kepada penerima di beberapa tempat di Facebook. Permintaan selalu bersifat pribadi dan hanya dapat dilihat oleh penerima. Meskipun satu permintaan dapat dikirim ke beberapa penerima sekaligus, penerima permintaan hanya dapat melihat detail pengirim dan tidak akan dapat melihat penerima lain dari permintaan tersebut.

Contoh Permintaan Game yang ditampilkan di Facebook untuk Desktop.

Permintaan game tersedia untuk Game di Facebook dan untuk game seluler di iOS dan Android. Di situs desktop Facebook, permintaan tampil sebagai popup bersuara di bagian kiri bawah layar dan di butir notifikasi juga, apabila tidak difilter. Di platform seluler, permintaan akan muncul di dalam daftar notifikasi di aplikasi Facebook, apabila tidak difilter. Data permintaan tersedia melalui API Permintaan Game, dan UIs khusus dapat dibangun untuk pengalaman yang lebih terintegrasi dalam game seluler. Oleh karena itu, penerapan permintaan Anda harus cocok dengan berbagai platform dan harus menyediakan pengalaman pengguna yang konsisten, apa pun platformnya. Namun, undangan yang dikirim oleh pemain akan tampil di berbagai kombinasi platform yang didukung oleh game Anda.

Membuka Dialog Permintaan

Dialog permintaan game dibuat melalui JavaScript, iOS, Android, dan Unity SDK. Contoh berikut mengasumsikan pengirim sudah mengautentikasi aplikasi. Jika tidak ada penerima yang ditetapkan, Anda dapat memfilter daftar teman dengan batas 50 teman atau kurang, dan Anda dapat membaginya berdasarkan pemain yang terdaftar atau teman yang belum terdaftar. Hal ini berguna untuk menyediakan alur terpisah untuk interaksi kembali atau undangan.

JavaScript

Mengirim permintaan menggunakan pemilih beberapa-teman yang disediakan oleh Dialog permintaan game:

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

Saat dialog ditutup, objek response akan berisi hasil kiriman tersebut, termasuk id request dan susunan penerima to. Contoh:

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

Secara default, pengirim akan melihat pemilih beberapa-teman yang memungkinkan mereka untuk memilih maksimal 50 penerima.

Mengirim permintaan ke penerima khusus:

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

Jika kolom to ditetapkan, pengirim tidak akan dapat memilih penerima tambahan.

Mengirim permintaan ke beberapa penerima khusus:

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

Penerima dalam jumlah banyak dapat ditentukan melalui daftar yang dipisahkan koma yang berisi ID Pengguna.

Mengirim permintaan ke daftar khusus teman:

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);
}});

Mengirim objek melalui permintaan, dengan secara jelas menyatakan action_type dan 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);
});

Untuk permintaan berbasis giliran, jangan tentukan 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);
});

Atau, penerima dapat dibagi dalam daftar bernama, sehingga pemain dapat memilih dari teman yang dikelompokkan secara logis berdasarkan statusnya di game.

Untuk informasi selengkapnya, lihat FB.ui dokumentasi referensi untuk Facebook SDK untuk JavaScript.

iOS SDK

Membuka dialog permintaan menggunakan pemilih teman yang disediakan oleh 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];

Mengirim permintaan yang secara jelas menyatakan action_type dan object_id ke penerima tertentu menggunakan iOS SDK:

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

Mengirim permintaan menggunakan pemilih teman dialog permintaan melalui 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);
}

Mengirim permintaan yang secara jelas menyatakan tindakan dan objek menggunakan 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

Berikut adalah bagaimana permintaan dilakukan di Unity SDK. Periksa dokumentasi FB.AppRequest untuk detail selengkapnya.

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
);

Parameter Dialog

Dialog Permintaan Game dapat dibuat dengan sejumlah parameter tambahan yang menentukan perilakunya. Parameter tersebut dijelaskan di bawah ini.

Data Tanggapan

Saat permintaan dikirimkan melalui dialog permintaan game, sebuah tanggapan akan diteruskan ke panggilan balik yang berisi informasi berikut:

Menangani Permintaan Dalam Game

Menerima Permintaan

Saat penerima menerima permintaan di situs desktop Facebook, dia akan diarahkan ke URL game yang mengirim permintaan tersebut. URL tersebut akan berisi parameter GET tambahan request_ids, yang merupakan daftar ID permintaan yang dipisahkan oleh koma yang diterima pengguna:

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

Permintaan tidak dihapus secara otomatis saat penerima menerimanya. Hal ini menjadi tanggung jawab game Anda. Pendekatan umumnya adalah saat game Anda dibuka, baca daftar permintaan yang belum dipenuhi dari Graph API untuk pengguna tersebut dan hapus setiap permintaan setelah diproses.

Saat penerima menerima permintaan di platform seluler, permintaan tersebut akan menautkan langsung ke dalam aplikasi. Sebuah parameter tambahan akan muncul saat aplikasi dimuat, yaitu ID permintaan. Tanggung jawab yang sama ketika menerima dan menghapus permintaan juga berlaku di seluler. Merupakan praktik yang baik untuk memeriksa dan menghapus permintaan yang tertunda pada peluncuran game.

Membaca permintaan

Setiap permintaan yang dikirim memiliki ID objek permintaan yang unik. ID ini mewakili objek permintaan. ID objek permintaan ini dapat digabungkan dengan ID pengguna penerima untuk membuat instance permintaan khusus. ID objek permintaan ini mewakili satu instantiasi permintaan, yang dikirimkan ke penerima tertentu.

Contohnya, saat mengirim permintaan, tanggapan dari Dialog Permintaan Game akan terlihat seperti berikut:

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

Jika Anda mencari ID objek permintaan melalui Graph API, tanggapan yang Anda terima akan sedikit berbeda, bergantung pada konteks tampilan pencarian tersebut, tetapi tanggapannya akan selalu mewakili seluruh objek permintaan.

Contoh, jika kueri ke http://graph.facebook.com/{REQUEST_OBJECT_ID}?access_token=USER_ACCESS_TOKEN dilakukan dengan token akses pengguna penerima, Anda akan melihat tanggapan berikut:

{
  "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"
}

Perhatikan bahwa kolom to dan from akan ditampilkan. Namun, jika endpoint yang sama dipanggil menggunakan token akses pengirim, atau token akses aplikasi, Facebook akan menampilkan hal berikut ini:

{
  "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"
}

Untuk mendapat permintaan lengkap yang menyertakan penerima yang menggunakan token akses aplikasi, Anda harus menambahkan ID pengguna penerima setelah karakter garis bawah '_'. Jadi contohnya, panggilan ke https://graph.facebook.com/{REQUEST_OBJECT_ID}_{USER_ID}?access_token={APP_ACCESS_TOKEN} akan menampilkan:

{
  "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"
}

Membaca semua permintaan

Agar dapat membaca semua permintaan untuk penerima, Anda dapat mengueri grafik sebagaimana ditunjukkan di bawah ini menggunakan USER ACCESS TOKEN penerima. Kueri ini akan menampilkan daftar id permintaan untuk pengguna tersebut di aplikasi.

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

Menghapus Permintaan

Permintaan Game tidak dihapus secara otomatis setelah diterima oleh penerima. Developer bertanggung jawab untuk menghapus permintaan setelah diterima. Anda harus menghapus permintaan atas nama pemain setelah permintaan diterima.

Anda dapat menghapus permintaan melalui metode berikut:

Graph API

Mengeluarkan permintaan HTTP DELETE ke request_id yang digabungkan:

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);
  });
}

Melacak Permintaan untuk referal dan hadiah

Anda dapat memberi hadiah kepada pengirim Permintaan Game berdasarkan tindakan tertentu yang dilakukan penerima sebagai hasilnya. Contohnya, Anda tidak dapat memberi hadiah kepada pemain hanya karena mengirim permintaan. Namun, jika penerima menginstal game dan mencapai level tertentu sebagai hasil dari menerima permintaan, Anda dapat memberi hadiah kepada pengirim tersebut.

Agar dapat memberi hadiah kepada pengirim, Anda harus mengetahui siapa yang akan diberi hadiah. Ada dua cara untuk melakukan hal ini:

1. Saat mengirimkan permintaan, simpan request_id yang ditampilkan di tanggapan dari dialog permintaan game dan cocokkan setelah diterima untuk memberi hadiah kepada pengirim.
2. Baca semua permintaan untuk pemain saat mereka membuka game, dan berikan hadiah kepada pengirim berdasarkan id di kolom from permintaan mereka. Jika beberapa teman sudah mengundang pemain, Anda dapat memilih untuk memberi hadiah kepada pengirim pertama atau semua pengirim.

Invitable Friends API

Pelokalan

Guna membantu Anda menawarkan pengalaman pengguna terbaik untuk pemirsa global, Facebook mendukung pelokalan untuk requests. Sebelum Anda menerjemahkan permintaan, Anda perlu mengetahui berbagai jenis permintaan dan cara permintaan tersebut ditampilkan. Permintaan dapat terlihat dalam bentuk standar “Anita mengirimi Anda permintaan” atau jika pasangan tindakan/objek ditetapkan, “Anita meminta Kehidupan dari Anda” atau “Anita mengirimi Anda Bom”. Ada juga permintaan giliran yang memberi tahu orang bahwa ini adalah giliran mereka dalam game melawan teman mereka. Semua contoh tersebut dilihat oleh pemain yang sudah mengautentikasi game. Jika penerima tidak menginstal game, dia akan melihat permintaan itu dalam bentuk undangan. Contohnya, “Anita mengundang Anda untuk bermain Friend Smash!”. Mari kita lihat cara menerjemahkan setiap undangan tersebut.

Menerjemahkan Undangan

Teks undangan diterjemahkan oleh Facebook secara otomatis dan tidak dapat dikontrol oleh developer. Teks ini diterjemahkan ke dalam bahasa penerima.

Notifikasi Undangan dalam bahasa Inggris

Notifikasi Undangan dalam bahasa Thai

Perhatikan dalam contoh di atas bahwa teks “invited you to play” otomatis diterjemahkan dalam bahasa lain, dalam hal ini bahasa Thai. Nama aplikasi dan deskripsi diterjemahkan di bagian “Lokalkan” di pengaturan aplikasi sebagai “Nama Tampilan” dan "Deskripsi", dalam kotak kuning di bawah ini.

Menerjemahkan Nama Tampilan dan Deskripsi Aplikasi

Permintaan juga dapat muncul di Pusat Aplikasi. Di Pusat Aplikasi, “pesan” permintaan ditampilkan. Pesan tersebut dapat diterjemahkan oleh developer. Dalam contoh di bawah ini, pesannya adalah "Can I have a life to help me through the next level" dalam bahasa Inggris dan " ช่วยส่งตัวเพิ่มให้หน่อย ต้องใช้ไปเลเวลหน้า" dalam bahasa Thai. Saat ini teks utama untuk permintaan, "Anita mengirimi Anda permintaan" tidak ditampilkan di Pusat Aplikasi.

Permintaan di Pusat Aplikasi dalam bahasa Inggris

Permintaan di Pusat Aplikasi dalam bahasa Thai

Menerjemahkan Pesan

Karena pesan diteruskan sebagai parameter saat dialog permintaan dipanggil, Anda dapat menerjemahkan sendiri pesan ini sebelum memanggil dialog permintaan dan meneruskan string yang diterjemahkan sebagai pesan. Jika Anda ingin mengubah terjemahan secara dinamis, Anda harus melakukannya sebelum memanggil dialog. Anda yang memutuskan bahasa mana yang ingin Anda tampilkan karena teksnya akan tetap sama dengan yang dilihat pengirim dalam cuplikan permintaan dan dilihat penerima saat menerima permintaan.

Banyak developer mendeteksi lokasi pengirim lalu menggunakannya untuk menentukan bahasa apa yang digunakan sebagai. Mereka berasumsi bahwa biasanya pengirim dan penerima berbicara dengan bahasa yang sama. Dalam contoh di atas, Anda dapat melihat lokasi pengirim, dan jika bahasanya adalah Thai, Anda dapat mengirimkan string dalam bahasa Thai secara langsung sebagai pesan, seperti ini:

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

Praktik Terbaik

Menambahkan data ke permintaan

Sebagaimana disebutkan di bagian Parameter Dialog di atas, Anda dapat menambahkan hingga 255 karakter data tambahan untuk dikirimkan bersama permintaan. Anda dapat menggunakan fasilitas ini untuk mentransfer informasi tambahan terkait permintaan atau menambahkan pengidentifikasi yang dapat Anda gunakan nanti untuk mencari informasi relevan yang disimpan di server Anda.

Sebagai contoh, dalam proyek game sampel Facebook Friend Smash, pemain bergiliran dalam bersaing untuk melakukan 'hancurkan' teman sebanyak-banyaknya. Saat seorang pemain mengirim tantangan ke pemain lain, melalui permintaan, parameter data digunakan untuk menyimpan skor terbaru pemain yang menantang tersebut. Game tersebut kemudian mengekstrak nilai ini untuk pemain yang menerima dan menjadikannya skor target untuk game berikutnya.

Memfilter undangan

Saat membuat pemilih beberapa-teman khusus atau memilih orang untuk dikirimi permintaan, pertimbangkan untuk menyediakan filter guna membantu pemain memilih penerima yang diinginkan.

Filter umum yang digunakan saat menerapkan undangan menggunakan dialog permintaan game adalah filter app_non_users. Filter ini mencegah dialog permintaan game menampilkan orang yang sebelumnya sudah memainkan game Anda. Filter lain yang dapat Anda pertimbangkan adalah pemain yang baru saja berinteraksi dengan atau pemain game serupa yang Anda kontrol. Untuk daftar lengkap filter yang tersedia, lihat dialog permintaan game - dokumen referensi parameter.

Buat mekanisme yang menarik

Buat mekanisme yang menarik untuk pemain saat mereka mengunjungi temannya di game atau berinteraksi langsung dengan mereka. Contohnya, jika game mendukung konsep tetangga, berikan bonus energi saat pemain mengunjungi lingkungan tetangga mereka. Jika markas pemain diserang, biarkan temannya membantu memperbaiki. Pemain umumnya menemukan nilai dalam membantu kemajuan temannya, dan memberi mereka kesempatan untuk melakukannya akan menghasilkan pengalaman sosial yang lebih besar dan lebih banyak orang yang bermain.

Jadikan objek bernilai bagi pemain

Tawarkan sesuatu yang bernilai kepada pemain yang dapat digunakan untuk meningkatkan gameplay atau pengalaman sosialnya.

Kelompokkan pemain dan tawarkan permintaan sesuai konteks

Evaluasi pemain Anda dan bagi mereka dalam berbagai kelompok yang sesuai untuk game Anda (mis, pemain baru, pemain yang sedang berkreasi, pemain yang memiliki banyak teman, pemain yang berinteraksi, dsb.). Pikirkan barang apa yang akan bermanfaat untuk mereka di level mereka dan tawarkan barang khusus untuk setiap segmen.