Menggunakan API Kongregate di Flash Games Anda

() translation by (you can also view the original English article)

Kongregate adalah salah satu portal permainan Flash terbesar di internet, dan memiliki API sendiri yang dapat diintegrasikan ke dalam permainan Anda (yang bahkan Kongregate memberi Anda imbalan secara finansial). Dalam tutorial ini, saya akan menunjukkan kepada Anda bagaimana menerapkan API Kongregate ke dalam gim Anda, dan juga menjelaskan secara mendetail tentang apa kemampuan API dan mengapa Anda harus menggunakannya.

(Perhatikan bahwa tutorial ini menganggap Anda sudah memiliki akun Kongregate; jika tidak, maka buatlah sekarang.)

Preview Hasil Akhir

Mari kita lihat apa API memungkinkan kita untuk melakukan:

Badges

Pesan Mass

Nilai Tertinggi

Ada alasan besar lain untuk menerapkan API ...

Langkah 1: Dapatkan Motivasi

Sebelum kita menyelam ke dalam aspek-aspek teknis pelaksanaan Kongregate API, mari kita mendapatkan diri hyped up sedikit, dan memastikan bahwa kita benar-benar ingin menerapkannya.

Ada banyak alasan untuk menerapkan API, tetapi bagi kebanyakan pengembang, tidak ada yang berbicara lebih keras daripada uang, dan ada banyak hal yang terlibat. Saat Anda mengunggah game ke Kongregate, Anda secara otomatis mendapatkan 25% dari semua pendapatan iklan yang dihasilkan oleh halaman gim Anda.

Semakin membaik; jika Anda menerapkan 'API Statistik & Tantangan', Anda akan menerima tambahan 10%! Akhirnya, jika game Anda eksklusif untuk Kongregate, atau disponsori oleh mereka, Anda menerima tambahan 15%. Ini memberi Anda peluang untuk mendapatkan hingga 50% dari pendapatan iklan untuk game Anda di Kongregate. Jika Anda bertanya-tanya berapa banyak, periksa beberapa statistik pribadi saya:

Langkah 2: Pengaturan lingkungan kerja

Untuk tutorial ini, kami akan menggunakan FlashDevelop, editor sumber terbuka gratis (dan luar biasa) untuk pengembang. Kami akan melakukan semuanya dengan mudah. Sebagai file, jadi jika Anda ingin mengikuti menggunakan Flash IDE, Anda tidak akan mengalami masalah. Jika Anda ingin menggunakan FlashDevelop dan tidak terbiasa dengannya, lihat panduan pemula FlashDevelop yang sangat baik ini untuk memulai tentang apa yang saya anggap sebagai editor AS3 terbaik di luar sana.

Untuk memulai, buka FlashDevelop, buka tab Project, dan pilih "New Project". Dari sini, pilih "AS3 Project dengan Pre-Loader". Atau, Anda bisa mengambil file Preloader.as dan Main.as dari pengunduhan sumber, dan cukup ikuti.

File harus sebuah file Main.as barebones, seperti ini:


package {
  import flash.display.Sprite;
	import flash.events.Event;

	/**
	 * ...
	 * @author Your Name
	 */
	
	[Frame(factoryClass = "Preloader")]
	
	public class Main extends Sprite {
		
		public function Main():void {
			if (stage) init();
			else addEventListener(Event.ADDED_TO_STAGE, init);
		}
		
		private function init(e:Event = null):void {
			removeEventListener(Event.ADDED_TO_STAGE, init);
			// entry point
		}
		
	}

}

Tidak ada yang di atas yang seharusnya baru bagi Anda; jika ya, yang perlu Anda ketahui adalah bahwa file ini adalah titik masuk untuk program kami, ini adalah tempat semuanya dimulai. Jika Anda mengkompilasi ini dengan FlashDevelop, Anda harus mendapatkan layar putih kosong, tanpa kesalahan kompiler.

Langkah 3: Mari Hubungkan

Sebelum kita masuk ke semua fitur keren dari API, kita perlu memastikan bahwa kita memiliki API dan berjalan.

Tidak seperti banyak API sponsor, API Kongregate bukan kumpulan file yang berdiri sendiri yang harus kita kompilasi dengan proyek kami. API sebenarnya disimpan di server Kongregate, dan kami memuatnya saat runtime. Ada sejumlah cara untuk melakukan ini dalam proyek Anda, tetapi demi tutorial ini, kami hanya akan terhubung dalam Main.as kami, dan menyimpan referensi untuk itu di sana.

Untuk memulai, salin kode berikut ke dalam file Main.as kami tepat di bawah impor yang ada:


import flash.display.LoaderInfo;
import flash.display.Loader;
import flash.net.URLRequest;
import flash.events.Event;
import flash.system.Security;

Di atas hanya beberapa impor sederhana yang akan memungkinkan kita untuk menggunakan kelas yang diperlukan untuk memuat di Kongregate API.

Selanjutnya, kita akan menambahkan variabel untuk menyimpan referensi kita ke API Kongregate. Lanjutkan dan tambahkan hak berikut di atas konstruktor file Main.as kami.

1
2	private var kongregate:*;

Perhatikan bahwa tipe data dari variabel kongregasi kita adalah *. Jika Anda tidak terbiasa dengan ini, kami hanya mengatakan kepada compiler bahwa variabel kongregate akan menerima jenis data apa pun, seperti wild card.

(Juga, perhatikan bahwa dalam permainan nyata Anda ingin menyimpan referensi Anda ke API di suatu tempat yang dapat diakses oleh seluruh proyek Anda, seperti const statis publik. Referensi ini diperlukan agar Anda dapat menggunakan API dari mana saja di proyek Anda, untuk tujuan apa pun, bukan hanya di file Main.as ketika kami pertama kali memulai.)

Potongan kode berikutnya ini akan terkandung dalam fungsi kustom dengan nama initKongregateAPI(). Ini sebenarnya tidak perlu, tetapi saya lebih suka merangkum berbagai ide saat menulis kode, karena membantu menjaga agar kode mudah dibaca dan mudah digunakan.

Lanjutkan dan tambahkan fungsi ini di bawah fungsi init di Main.as.


private function initKongregateAPI():void {
	// Pull the API path from the FlashVars
	var paramObj:Object = LoaderInfo(root.loaderInfo).parameters;
			
	// The API path. The "shadow" API will load if testing locally. 
	var apiPath:String = paramObj.kongregate_api_path || 
	"http://www.kongregate.com/flash/API_AS3_Local.swf";
			
	// Allow the API access to this SWF
	Security.allowDomain(apiPath);
			
	// Load the API
	var request:URLRequest = new URLRequest(apiPath);
	var loader:Loader = new Loader();
	loader.contentLoaderInfo.addEventListener(Event.COMPLETE, loadComplete);
	loader.load(request);
	this.addChild(loader);			
}

Sementara yang mungkin tampak seperti banyak kode, itu benar-benar tidak banyak, dan dengan komentar, dan akan sangat mudah untuk mengikuti.

Seperti yang Anda lihat, di bagian pertama kami menciptakan sebuah variabel untuk menyimpan jalan API dari FlashVars (jika Anda tidak tahu apa arti semuanya ini, lihat mereka sampai benar-benar cepat, mereka adalah hal yang besar untuk memahami).

Dalam bongkahan kedua, kita menentukan apakah SWF di Kongregate website atau berjalan secara lokal, dan kami memberikan informasi yang tepat ke variabel apiPath.

Selanjutnya, kami memberikan akses API ke SWF, dengan panggilan sederhana security.allowDomain, dimana kita lulus dalam apiPath sebagai parameter.

Kami kemudian membuat objek URLRequest baru, yang mendapat apiPath berlalu dalam ke konstruktor, objek Loader baru, dan menambahkan acara pendengar untuk loader yang akan memanggil loadComplete ketika selesai.

Terakhir, kami memanggil loader.load dan meneruskan permintaan kami (objek URLRequest yang baru dibuat, yang berisi apiPath dari API Kongregate). Jika Anda mengerti apa yang baru saja terjadi, hebat; jika tidak, jangan dipikirkan, karena Anda tidak perlu menyentuh ini lagi.

Jangan Lupa Memanggilnya!

Sekarang setelah fungsi initKongregateAPI dibuat, dan berisi semua kode koneksi, kita mungkin harus memastikan fungsi ini benar-benar dipanggil! Cukup kembali ke fungsi init bahwa file Main.as kami sudah ada, dan tambahkan panggilan fungsi ke initKongregateAPI setelah baris yang 'entry point', seperti begitu,


private function init(e:Event = null):void {
	removeEventListener(Event.ADDED_TO_STAGE, init);
	// entry point
	
	initKongregateAPI();
}

Akhirnya, kita perlu menambahkan fungsi loadComplete, untuk dipanggil ketika acara COMPLETE dipecat dari kode sebelumnya. Tambahkan fungsi ini di bawah fungsi initKongregateAPI di Main.as.


// This function is called when loading is complete
private function loadComplete(event:Event):void {
	// Save Kongregate API reference
	kongregate = event.target.content;
		
	// Connect to the back-end
	kongregate.services.connect();
			
	// You can now access the API via:
	// kongregate.services
	// kongregate.user
	// kongregate.scores
	// kongregate.stats
	// etc...
}

Kode di atas sangat sederhana; mari kita lanjutkan. Kami memulai dengan menyimpan referensi ke API Kongregate. Seperti yang Anda lihat, kami mereferensikan API Kongregate melalui parameter event yang dilewatkan, melalui event.target.content - cukup sederhana.

Sekarang yang harus kita lakukan hanyalah terhubung, dan SWF kita baik untuk dipakai.Seperti yang anda lihat, kita terhubung dengan memanggil method kongregate.services.connect Tidak perlu pakai argumen.

Sementara itu, mungkin tampak seperti banyak pekerjaan, sebenarnya tidak. Saya hanya membahas proses koneksi dalam perincian yang banyak, sehingga Anda dapat memahami bagaimana kami sebenarnya mendapatkan akses ke API, daripada hanya memiliki akses itu dan menggunakannya. Sekarang setelah Anda memahaminya, Anda dapat menggunakan semua kode boilerplate di atas.

Langkah 4: Statistika & Tantangan API

Setelah terhubung, kita dapat melihat fitur terpenting dari keseluruhan API: bagian statistic & Tantangan. API ini mengirimkan statistik terkait pemain ke server Kongregate, yang memungkinkan sejumlah hal.

Pertama, ini adalah cara paling dasar untuk memungkinkan pemain bersaing untuk mendapatkan skor tinggi di Kongregate. Dengan API terintegrasi, side bar Kongregate akan menyertakan tab baru berlabel "ACHIEVEMENTS", yang dapat ditemukan di sebelah tab "CHAT". Pemain dapat melihat papan peringkat untuk statistik yang Anda kirim ke server, yang bisa berupa apa pun dari skor tinggi dasar hingga jumlah total musuh yang dikalahkan.

Penggunaan kedua dan jauh lebih penting, adalah memungkinkan Kongregate menggunakan statistik yang Anda kirimkan untuk membuat "lencana" untuk permainan Anda. Lencana adalah bagian sentral dari pengalaman pengguna Kongregate, dan sangat mirip dengan sistem pencapaian pada platform seperti Xbox LIVE.

Bagian terbaik tentang menambahkan lencana ke permainan Anda adalah bahwa game Anda akan menjadi fitur untuk durasi pendek, sangat meningkatkan jumlah tampilan yang Anda dapatkan, dan dengan demikian sangat meningkatkan pendapatan iklan Anda. Bahkan setelah game Anda keluar dari sorotan, semua game di Kongregate terus menerima peningkatan tampilan diatas game normal, yang memberi Anda aliran pendapatan jangka panjang yang sangat baik.

Perhatikan bahwa lencana tidak ditambahkan oleh pengembang, tetapi dibuat oleh staf Kongregate. Anda akan membutuhkan game berperingkat tinggi untuk dipilih, tetapi Anda juga memerlukan API untuk disiapkan - jadi mari kita raih setengah dari pertempuran!

Langkah 5: Persiapan Backend

Untuk benar - benar menggunakan statistik yang akan kita kirim, pertama - tama Kongregate terlebih dahulu mengharuskan kita untuk memberi tahu server mereka informasi apa yang harus disiapkan untuk menerima dari kita.

Untuk melakukan ini, kita cukup pergi ke halaman Statistik untuk permainan kita di situs web Kongregate. Ini dapat ditemukan di halaman "Edit Game" page, atau dengan menambahkan /statistics di akhir URL permainan anda (contohnya, http://www.kongregate.com/games/EpicShadow/pixel-purge/statistics). Untuk tutorial ini, kami hanya akan mengunggah SWF test kami sebagai "permainan".

Sebelum menambahkan statistik apapun ke Statistika & Tantangan API, pertama-tama kita harus memahami empat jenis statistik yang dapat digunakan, dan aturan yang harus mereka patuhi. Nilai harus bernilai positif, dan harus berupa bilangan bulat (integer) . Keempat jenis itu adalah sebagai berikut:

Max: Nilai pada server akan diganti jika nilai baru lebih tinggi dari nilai yang disimpan. Misalnya, skor tinggi 152.000 akan menggantikan skor tinggi yang lama yaitu 120.000.
Min: Nilai pada server akan diganti jika nilai baru lebih rendah dari nilai yang disimpan. Misalnya, dalam permainan balap, waktu lap 31 detik akan menggantikan nilai yang lebih lama yaitu 35.
Add: Nilai baru akan ditambahkan ke nilai yang disimpan. Penggunaan umum dari ini adalah total musuh yang dikalahkan, kematian pemain, dll. Terlalu banyak permintaan ke server dapat mengakibatkan data yang tidak akurat, sehingga disarankan bahwa data hanya dikirim dalam jumlah besar, seperti ketika tingkat selesai atau ketika pemain meninggal.
Replace: Nilai baru akan menggantikan nilai yang tersimpan. Ini dapat digunakan untuk sejumlah hal, seperti waktu kelangsungan hidup rata-rata atau peringkat pemain.

Mengetahui jenis-jenis di atas yang perlu Anda gunakan untuk setiap statistik permainan Anda sangat penting, jadi pastikan Anda membiasakan diri dengan daftar di atas. Anda pasti menginginkan daftar statistik yang Anda inginkan untuk dikirim ke Kongregate, jadi pastikan Anda menyiapkannya sebelum masuk ke langkah berikutnya ketika benar-benar mengirimkan game.

Demi kebaikan tutorial ini, kami hanya akan menggunakan statistik berikut:

Total Klik (Add)
Maksimal Klik (Max)
Terakhir X (Replace)

Setelah daftar Anda disiapkan, buka halaman Statistik permainan Anda, dan masukkan data yang diperlukan. Setelah pekerjaan back-end dilakukan pada halaman Statistik, permainan akan siap untuk mengirimkan data ke server Kongregate.

Step 6: Cara Untuk Mengirim Statistik

Untuk benar-benar mengirim data ke server, kita cukup memanggil fungsi "submit", yang terlihat seperti ini:

1
2	submit(statName:String, value:Number):void

Seperti yang anda lihat, fungsi mengambil dua parameter:

statName adalah nama dari statistik anda. Sangat penting bahwa String yang dilewatkan adalah identik (peka huruf besar kecil) dengan nama stat yang Anda cantumkan pada langkah sebelumnya ketika mempersiapkan server untuk menangani statistik Anda.
value adalah nilai numerik aktual yang dilewatkan. Meskipun tipe datanya adalah Number, ingat bahwa nilai Anda harus berupa bilangan bulat positif.

Untuk memanggil fungsi ini di permainan Anda, cukup lakukan hal berikut:

1
2	kongregate.stats.submit(“Your Stat String”, statValue);
3	//stat value could be 1, 500, 5342324, etc.

Meskipun kita memiliki empat jenis statistik yang berbeda yang dapat kita kirim, fungsi ini hanya mengirimkan nilainya; server itu sendiri akan melihat informasi yang kita berikan pada langkah sebelumnya untuk menentukan bagaimana memperlakukan data yang masuk. Sesederhana itu; sekarang kita tahu cara mengirim data ke server.

Step 7: Mempersiapkan Proyek Kita untuk Mengirim Statistik

Sekarang setelah kita menyiapkan back-end di situs web Kongregate, dan sekarang kita tahu cara mengirim data, Mari kita coba pada proyek ini!

Hal pertama yang perlu kita lakukan adalah menambahkan beberapa kode ke proyek kita untuk benar-benar mengirim statistik. Karena hal termudah untuk dilacak adalah input mouse, saya memilih statistik terkait mouse. Seperti yang Anda lihat di langkah sebelumnya, saya memilih Klik Max, Klik Total, dan Last X.

Max Clicks akan menjadi skor tinggi untuk berapa kali kita mengklik dalam satu kali permainan, untuk menunjukkan tipe Max; Total Klik akan menjadi jumlah total semua klik yang telah kita lakukan, untuk mendemonstrasikan jenis Add; dan Last X akan menjadi posisi x dari klik terakhir kita, untuk mendemokan tipe Replace.

Untuk melacak klik Mouse kita, kita perlu mengimpor class MouseEvent. Kembali ke Main.as, dan tambahkan yang berikut ini ke dalam import anda:

1
2	import flash.events.MouseEvent;

Sekarang kita perlu menambahkan variabel untuk statistik Klik Max kita, untuk melacak jumlah total klik per sesi permainan. Tepat di bawah tempat kami menambahkanvariabel referensi Kongregate (dari tipe data *), tambahkan yang sebagai berikut:

1
2	private var maxClicks:int;

Kita akan memerlukan sebuah Event Listener untuk merespon Klik kita, maka, kitta akan menambahkannya sekarang. Dalam fungsi init, tepat dibawah panggilan untuk memanggil initKongregateAPI, tambahkan yang berikut ini:

1
2	//Event listener for mouse clicks
3	stage.addEventListener(MouseEvent.CLICK, clicked);

Seperti yang Anda lihat pada kode di atas, fungsi yang dipanggil setiap kali peristiwa itu diaktifkan disebut clicked. Mari kita lanjutkan dan buat fungsi itu. Tambahkan yang berikut di bawah function loadComplete:


private function clicked(event:Event):void {
	maxClicks++;
	kongregate.stats.submit("Total Clicks", 1);
	kongregate.stats.submit("Max Clicks", maxClicks);
	kongregate.stats.submit("Last X", mouseX);
}

Yang kami lakukan di sini adalah menambah variabel maxClicks sebesar 1, dan kemudian mengirimkan semua informasi yang diperlukan ke server Kongregate. Ini akan menambah 1 ke stat Total Clicks, mengirim variabel maxClicks saat inike server, yang kemudian akan menentukan apakah lebih tinggi dari nilai sebelumnya dan menggantikannya jika demikian, dan mengirim posisi x dari klik sebelumnya, yang secara otomatis akan menggantikan nilai sebelumnya.

SWF kita mungkin hanya layar kosong, tetapi banyak yang terjadi, dan kita akan melihatnya dalam aksi. Pastikan Anda meng-compile proyek sebelum pindah.

Langkah 8: Menguji Proyek Kita

Sekarang saatnya untuk benar-benar upload proyek kami, dan melihatnya dalam tindakan.

Kembali ke situs web Kongregate, buka halaman permainan Anda, dan unggah versi terakhir dari proyek kita. Setelah Anda mengunggah proyek, Anda akan dibawa ke layar pratinjau, tempat kita dapat menguji proyek kita sebelum mempublikasikannya. Untuk staf Kongregate menghemat banyak waktu dan energi, melakukan semua kebaikan dan tidak tekan mempublikasikan di menguji SWF. (Jika Anda bekerja pada permainan nyata, pergi ke depan, tapi demi tutorial ini kita akan tidak menerbitkan proyek ini.)

Setelah Anda berada di halaman pengujian, berikan game beberapa klik. Segarkan halaman, dan Anda sekarang harus melihat bahwa ada tab "HIGH SCORES" di sebelah tab "CHAT" dan "GAME". Jika Anda telah melakukan semuanya dengan benar hingga titik ini, Anda harus memiliki kotak drop-down yang saat ini membaca "Last X" yang juga berisi "Max Clicks" dan "Total Clicks". Perhatikan bahwa mengeklik dengan cepat akan menghasilkan statistik tidak akurat, karena server tidak dapat mengikuti semua permintaan, jadi klik perlahan untuk hasil terbaik. nilah sebabnya mengapa saya menyarankan sebelumnya jika Anda mengirim sejumlah besar data setelah mati dalam game, atau penyelesaian level, bila memungkinkan.

Nah begitulah: Anda sekarang memiliki bagian paling penting dari API Kongregate dan berjalan. Jika proyek Anda tidak berfungsi pada titik ini, pastikan bahwa nama-nama stat back-end Kongregate Anda diketik sama persis seperti pada fungsi submit Anda - case-sensitive - karena biasanya itu masalahnya.

Anda juga dapat melihat code lengkapnya di folder files akhir di dalam source unduhan, jadi bandingkan kode Anda dengan itu jika Anda masih mengalami masalah.

Langkah 9: Komunikasi Pesan Massa

Pernah merilis game, kemudian, benar-benar ingin menjangkau semua penggemar Anda? Nah, dengan API Kongregate, Anda dapat melakukan hal itu - setidaknya, untuk semua penggemar Kongregate Anda.

Ada beberapa batasan pada siapa yang dapat melakukan ini, tetapi batasan ini sangat sesuai untuk kepentingan pengembang dan pemain. Agar memenuhi syarat, game Anda harus menerima rating 3,75 atau lebih tinggi, dan memiliki setidaknya 10 ribu game play.

Anda dapat mengirim pesan "active players" paling banyak setiap tujuh hari sekali. Pesan-pesan ini akan dikirim ke setiap pemain yang telah memainkan game setidaknya tiga kali, dan setidaknya sekali dalam sepuluh hari terakhir.

Anda dapat mengirim pesan "Inactive players" paling banyak setiap 30 hari sekali. Pesan-pesan ini akan diterima oleh pemain yang telah bermain setidaknya lima kali total, tetapi tidak dalam sepuluh hari terakhir.

Ada banyak alasan untuk mengirim pesan ini ke pemain Anda, seperti memperingatkan mereka tentang perbaikan bug, atau mungkin memberi tahu mereka tentang sekuel yang akan datang. Terlepas dari apa yang Anda gunakan untuk ini, ini adalah sistem yang sangat berguna yang benar-benar dapat membantu Anda memanfaatkan penggemar Anda.

Untuk informasi lebih lanjut, Baca petunjuk ini.

Jauh Lebih banyak lagi ...

Meskipun kami telah membahas banyak hal dalam tutorial ini, API Kongregate mampu melakukan lebih banyak lagi. Sayangnya, saya harus menulis sebuah buku kecil untuk membahas semua fitur, terutama yang berguna untuk MMO berbasis web. Jika Anda tertarik untuk memeriksa fitur lain apa yang ditawarkan API, saya sarankan untuk melihat Pusat Pengembang Kongregate untuk informasi lebih lanjut.

Sekarang setelah Anda tahu cara membuat dan menjalankan API Kongregate, saya sangat menyarankan Anda untuk menambahkannya ke semua game anda di masa depan; jika Anda beruntung, Anda bahkan mungkin mendapatkan beberapa lencana, dan saat itulah kesenangan yang sesungguhnya dimulai.