Kongregate — это один из крупнейших порталов Flash-игр в сети, имеющий собственный API, который можно интегрировать в ваши игры (за что Kongregate даже вознаграждает вас финансово). В этом руководстве я покажу вам, как внедрить API Kongregate в ваши игры, а также подробно расскажу о том, на что способен API и почему вы должны его использовать.
(Обратите внимание, что в этом руководстве предполагается, что у вас уже есть аккаунт в Kongregate; если у вас его нет, создайте его сейчас .)
Окончательный результат предварительного просмотра
Давайте посмотрим, что API позволяет нам делать:
Значки
Массовые сообщения
Высокие результаты
Есть еще одна важная причина для реализации API …
Шаг 1: Давайте будем мотивированы
Прежде чем мы углубимся в технические аспекты реализации API Kongregate, давайте немного раскусим себя и убедимся, что мы действительно хотим его реализовать.
Есть много причин для реализации API, но большинству разработчиков ничто не говорит громче денег, и в этом есть много чего. Когда вы загружаете свою игру в Kongregate, вы автоматически получаете 25% от всех доходов от рекламы, полученных на странице вашей игры.
Становится лучше; если вы реализуете их «Статистика и API вызовов», вы получите дополнительно 10%! Наконец, если ваша игра предназначена исключительно для Kongregate или спонсируется ими, вы получаете дополнительные 15%. Это дает вам возможность получать до 50% дохода от рекламы для вашей игры в Kongregate. Если вам интересно, сколько это стоит, посмотрите некоторые из моих личных статистических данных:
Шаг 2: Настройка нашей рабочей среды
Для этого урока мы будем использовать FlashDevelop , бесплатный (и удивительный) редактор с открытым исходным кодом для разработчиков. Мы будем делать все в простых файлах .as, поэтому, если вы хотите использовать Flash IDE, у вас не должно возникнуть никаких проблем. Если вы хотите использовать FlashDevelop и не знакомы с ним, ознакомьтесь с этим прекрасным руководством для начинающих по FlashDevelop, чтобы вы могли начать работу с тем, что я считаю лучшим редактором AS3.
Для начала откройте FlashDevelop, перейдите на вкладку «Проект» и выберите «Новый проект». Отсюда выберите «Проект AS3 с предварительным загрузчиком». Кроме того, вы можете взять файлы Preloader.as и Main.as из исходной загрузки и просто следовать за ними.
Ваш файл должен быть Main.as файлом Main.as , например так:
|
01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
|
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
}
}
}
|
Ничто из вышеперечисленного не должно быть новым для вас; если это так, все, что вам нужно знать, — это то, что этот файл является точкой входа для нашей программы, с этого все и начинается. Если вы скомпилируете это с помощью FlashDevelop, вы должны получить пустой белый экран без ошибок компиляции.
Шаг 3: Давайте подключимся
Прежде чем мы углубимся во все интересные функции API, мы должны убедиться, что у нас есть API, запущенный и работающий.
В отличие от многих API-интерфейсов спонсоров, Kongregate API не является отдельным набором файлов, которые нам необходимо скомпилировать с нашим проектом. API фактически хранится на сервере Kongregate, и мы загружаем его во время выполнения. Есть несколько способов сделать это в ваших проектах, но ради этого урока мы просто подключимся к нашему Main.as и сохраним ссылку на него там.
Для начала скопируйте следующий код в наш файл Main.as чуть ниже существующего импорта:
|
1
2
3
4
5
|
import flash.display.LoaderInfo;
import flash.display.Loader;
import flash.net.URLRequest;
import flash.events.Event;
import flash.system.Security;
|
Выше приведены лишь несколько простых импортов, которые позволят нам использовать необходимые классы для загрузки в Kongregate API.
Далее мы добавим переменную для хранения нашей ссылки на Kongregate API. Идите дальше и добавьте следующее прямо над конструктором нашего файла Main.as.
|
1
|
private var kongregate:*;
|
Обратите внимание, что тип данных нашей переменной kongregate — * . Если вы не знакомы с этим, мы просто kongregate компилятору, что переменная kongregate будет принимать любой тип данных, почти как kongregate .
(Также обратите внимание, что в реальной игре вы хотите хранить ссылку на API где-то, к чему имеет доступ весь ваш проект, такой как public static const . Эта ссылка необходима, чтобы вы могли использовать API из любой точки ваш проект для любых целей, а не только в файле Main.as при первом запуске.)
Этот следующий фрагмент кода будет содержаться в пользовательской функции с именем initKongregateAPI() . На самом деле в этом нет необходимости, но я предпочитаю инкапсулировать идеи при написании кода, поскольку он помогает сделать код читабельным и с ним легко работать.
Main.as добавим эту функцию ниже функции init в Main.as
|
01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
18
|
private function initKongregateAPI():void {
// Pull the API path from the FlashVars
var paramObj:Object = LoaderInfo(root.loaderInfo).parameters;
// The API path.
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);
}
|
Хотя это может выглядеть много кода, на самом деле это не так много, и с комментариями, это довольно легко следовать.
Как вы увидите, в первой части мы создаем переменную для хранения пути API из FlashVars (если вы не знаете, что это такое, ищите их очень быстро , это хорошая вещь для понимания) ,
Во втором блоке мы определяем, находится ли SWF на веб-сайте Kongregate или работает локально, и назначаем правильную информацию для переменной apiPath .
Далее мы предоставляем API-доступ к SWF с помощью простого вызова security.allowDomain , где мы передаем в качестве параметра apiPath .
Затем мы создаем новый объект URLRequest , который получает apiPath переданный в конструктор, новый объект Loader , и добавляем прослушиватель событий для загрузчика, который будет вызывать loadComplete завершении.
Наконец, мы вызываем loader.load и передаем наш запрос (недавно созданный объект URLRequest , который содержит apiPath API Kongregate). Если вы понимаете, что только что произошло, прекрасно; если нет, не переживайте, так как вам не придется снова это трогать.
Не забудьте позвонить!
Теперь, когда функция initKongregateAPI создана и содержит весь код соединения, мы, вероятно, должны убедиться, что эта функция действительно вызывается! Просто вернитесь к функции init которая уже содержится в нашем файле Main.as , и добавьте вызов функции к initKongregateAPI после строки, в initKongregateAPI находится строка «точки входа», например,
|
1
2
3
4
5
6
|
private function init(e:Event = null):void {
removeEventListener(Event.ADDED_TO_STAGE, init);
// entry point
initKongregateAPI();
}
|
Наконец, нам нужно добавить эту функцию loadComplete , которая будет вызываться при COMPLETE события COMPLETE из нашего предыдущего кода. Добавьте эту функцию ниже функции Main.as в Main.as
|
01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
|
// 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…
}
|
Код выше очень прост; давай пройдемся. Мы начнем с сохранения ссылки на Kongregate API. Как вы можете видеть, мы ссылаемся на API Kongregate через переданный параметр события, через event.target.content — достаточно просто.
Теперь все, что нам нужно сделать, это подключиться, и наш SWF готов к работе. Как видите, мы подключаемся, вызывая метод kongregate.services.connect . Никаких аргументов не требуется.
Хотя это могло показаться большой работой, на самом деле это не так. Я просто подробно рассмотрел процесс подключения, чтобы вы могли понять, как мы на самом деле получаем доступ к API, а не просто имеем этот доступ и используем его. Теперь, когда вы понимаете это, вы можете использовать все вышеперечисленное в качестве стандартного кода.
Шаг 4. API статистики и вызовов
Теперь, когда мы подключены, мы можем взглянуть на самую важную особенность всего API: раздел Статистика и задачи. Этот API отправляет статистику игрока на сервер Kongregate, что позволяет делать несколько вещей.
Во-первых, это самый простой способ позволить пользователям побороться за высокие оценки в Kongregate. Благодаря встроенному API боковая панель Kongregate будет содержать новую вкладку с надписью «ДОСТИЖЕНИЯ», которую можно найти рядом с вкладкой «ЧАТ». Игроки могут просматривать списки лидеров для любой статистики, которую вы отправляете на серверы, которая может быть любой, от простого высокого счета до общего количества побежденных врагов.
Второе и гораздо более важное использование — это позволить Kongregate использовать предоставленную вами статистику для создания «значков» для ваших игр. Значки являются центральной частью пользовательского интерфейса Kongregate и очень похожи на системы достижений на таких платформах, как Xbox LIVE.
Самое приятное в добавлении значков в вашу игру — это то, что ваша игра появится на короткое время, что значительно увеличит количество просмотров, которые вы получаете, и, таким образом, значительно увеличит ваш доход от рекламы. Даже после того, как ваша игра окажется в центре внимания, все игры под маркой в Kongregate продолжают получать увеличенное количество просмотров по сравнению с обычными играми, что дает вам отличный источник дохода с длинным хвостом.
Обратите внимание, что значки не добавляются разработчиками, а создаются сотрудниками Kongregate. Для выбора вам понадобится игра с высоким рейтингом, но вам также понадобится настроить API — так что давайте уберем половину битвы!
Шаг 5: Бэкэнд Подготовка
Чтобы использовать статистику, которую мы будем отправлять, Kongregate сначала требует, чтобы мы сообщили их серверу, какую информацию он должен получить от нас.
Для этого мы просто перейдем на страницу статистики для нашей игры на сайте Kongregate. Это можно найти на странице «Редактировать игру» или добавив /statistics в конец URL-адреса вашей игры (например, http://www.kongregate.com/games/EpicShadow/pixel-purge/statistics ). Для этого урока мы просто загрузим наш тестовый SWF как «игру».
Перед добавлением какой-либо статистики в API Statistics & Challenges нам необходимо сначала понять четыре типа статистики, которые можно использовать, и правила, с которыми они связаны. Значения должны быть положительными и должны быть целыми числами . Четыре типа следующие:
- Макс . Значение на сервере будет заменено, если новое значение превысит сохраненное значение. Например, высокий балл 152 000 заменит старый высокий балл 120 000.
- Мин: значение на сервере будет заменено, если новое значение меньше сохраненного значения. Например, в гоночной игре время круга 31 секунда заменит старшее значение 35.
- Добавить: новое значение будет добавлено к сохраненному значению. Распространенным применением этого будет общее количество побежденных врагов, гибель игроков и т. Д. Слишком много запросов к серверу может привести к неточным данным, поэтому рекомендуется, чтобы данные отправлялись только оптом, например, когда уровень завершен или когда игрок плашки.
- Заменить: новое значение заменит сохраненное значение, несмотря ни на что. Это может быть использовано для ряда вещей, таких как среднее время выживания или рейтинг игрока.
Знание того, какой из перечисленных типов вам необходимо использовать для каждой игровой статистики, чрезвычайно важно, поэтому обязательно ознакомьтесь с приведенным выше списком. Вам, очевидно, понадобится список статистических данных, которые вы хотите, чтобы ваша игра отправляла в Kongregate, поэтому убедитесь, что вы подготовили их, прежде чем погрузиться в следующий шаг при фактической отправке игры.
Для этого урока мы просто будем использовать следующую статистику:
- Всего кликов (Добавить)
- Макс кликов (макс)
- Последний Х (Заменить)
Как только ваш список подготовлен, перейдите на страницу статистики вашей игры и введите необходимые данные. После выполнения серверной работы на странице статистики игра будет готова отправить данные на сервер Kongregate.
Шаг 6: Как отправить статистику
Для фактической отправки данных на сервер мы просто вызываем функцию submit, которая выглядит следующим образом:
|
1
|
submit(statName:String, value:Number):void
|
Как видите, функция принимает два параметра:
-
statName— это имя вашей статистики. Очень важно, чтобы передаваемая строка была идентична (с учетом регистра) имени статистики, которую вы указали на предыдущем шаге при подготовке сервера к обработке вашей статистики. -
value— фактическое числовое значение, которое будет передано. Даже если тип данных Number, помните, что ваше значение должно быть целым положительным целым числом .
Чтобы вызвать эту функцию в своей игре, просто сделайте следующее:
|
1
2
|
kongregate.stats.submit(“Your Stat String”, statValue);
//stat value could be 1, 500, 5342324, etc.
|
Хотя у нас было четыре разных типа статистики, которые мы могли отправить, эта функция только отправляет значение; сам сервер будет смотреть на информацию, которую мы предоставили на предыдущем шаге, чтобы определить, как обрабатывать входящие данные. Это так просто; Теперь мы знаем, как отправить данные на сервер.
Шаг 7: Подготовка нашего проекта к отправке статистики
Теперь, когда мы подготовили бэкэнд на веб-сайте Kongregate и теперь знаем, как отправлять данные, давайте попробуем этот проект.
Первое, что нам нужно сделать, это добавить некоторый код в наш проект для фактической отправки нашей статистики. Поскольку проще всего отслеживать ввод с помощью мыши, я выбрал статистику, связанную с мышью. Как вы видели на предыдущем шаге, я выбрал Макс. Кликов, Всего кликов и Последний X.
Максимальное количество кликов будет лучшим показателем того, сколько раз мы кликаем в одной игре, чтобы продемонстрировать тип Max; Всего кликов будет общая сумма всех кликов, которые мы сделали, чтобы продемонстрировать тип добавления; и Last X будет позицией x нашего последнего клика, чтобы продемонстрировать тип Replace.
Чтобы отслеживать наши щелчки мышью, нам нужно импортировать класс MouseEvent . Вернитесь на Main.as и добавьте следующее в ваш импорт:
|
1
|
import flash.events.MouseEvent;
|
Теперь нам нужно добавить переменную для нашей статистики по максимальному количеству кликов, чтобы отслеживать общее количество кликов за игровую сессию. Прямо ниже, где мы добавили kongregate переменную kongregate (типа данных * ), добавьте следующее:
|
1
|
private var maxClicks:int;
|
Нам понадобится прослушиватель событий для прослушивания наших кликов, поэтому мы добавим это сейчас. В функции init , прямо под вызовом initKongregateAPI , добавьте следующее:
|
1
2
|
//Event listener for mouse clicks
stage.addEventListener(MouseEvent.CLICK, clicked);
|
Как вы можете видеть в приведенном выше коде, функция вызывается всякий раз, когда вызывается вызванное ею событие. Давайте продолжим и создадим эту функцию. Добавьте следующее ниже вашей функции loadComplete :
|
1
2
3
4
5
6
|
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);
}
|
Все, что мы здесь делаем, это увеличиваем переменную maxClicks на 1 , а затем отправляем всю необходимую информацию на сервер Kongregate. Это добавит 1 к статистике Total Clicks, отправит текущую переменную maxClicks на сервер, который затем определит, является ли она выше предыдущего значения, и заменит ее, если так, и отправит позицию x нашего предыдущего клика, которая автоматически заменить предыдущее значение.
Наш SWF может быть просто пустым экраном, но многое происходит, и мы собираемся увидеть его в действии. Убедитесь, что вы скомпилировали проект, прежде чем двигаться дальше.
Шаг 8: Тестирование нашего проекта
Теперь пришло время загрузить наш проект и увидеть его в действии.
Вернитесь на сайт Kongregate, перейдите на страницу игры и загрузите финальную версию нашего проекта. После загрузки проекта вы попадете на экран предварительного просмотра, где мы можем протестировать наш проект перед его публикацией. Чтобы сэкономить персоналу Kongregate много времени и сил, сделайте всем одолжение и не нажимайте кнопку «опубликовать» в своем тестовом SWF. (Если вы работаете над реальной игрой, продолжайте, но ради этого урока мы не будем публиковать этот проект.)
Попав на тестовую страницу, дайте игре несколько кликов. Обновите страницу, и вы должны увидеть, что рядом с вкладками «ЧАТ» и «ИГРА» есть вкладка «ВЫСОКИЕ ОЦЕНКИ». Если вы все сделали правильно до этого момента, у вас должен быть выпадающий список с надписью «Last X», который также содержит «Max Clicks» и «Total Clicks». Обратите внимание, что быстрое нажатие приведет к неточной статистике, поскольку сервер не может справиться со всеми запросами, поэтому нажимайте медленно, чтобы получить наилучшие результаты. Вот почему я ранее советовал отправлять большие пакеты данных после смерти или завершения уровня, когда это возможно.
Ну, вот и все: теперь у вас есть самая важная часть API Kongregate. Если ваш проект на данный момент не работает, убедитесь, что ваши внутренние статистические имена Kongregate набраны в точности так, как они есть в вашей функции отправки — с учетом регистра — так как обычно это проблема.
Вы также можете найти готовый код в папке окончательных файлов в исходной загрузке , поэтому сравните ваш код с этим, если у вас все еще есть проблемы.
Шаг 9: Массовая передача сообщений
Когда-нибудь выпускали игру, а потом действительно хотели пообщаться со всеми своими фанатами? Что ж, с API Kongregate вы можете сделать это — по крайней мере, для всех своих поклонников Kongregate.
Есть некоторые ограничения на то, кто может сделать это, но эти ограничения в значительной степени отвечают интересам как разработчиков, так и игроков. Чтобы пройти отбор, ваша игра должна получить рейтинг 3,75 или выше и иметь как минимум 10 тысяч игровых процессов.
Вы можете отправлять сообщения «активных игроков» не чаще одного раза в семь дней. Эти сообщения будут отправлены всем игрокам, которые играли в игру не менее трех раз и хотя бы один раз за последние десять дней.
Вы можете отправлять сообщения «неактивных игроков» не чаще, чем раз в 30 дней. Эти сообщения будут получены любыми игроками, которые сыграли как минимум пять раз, но не в течение последних десяти дней.
Есть много причин отправлять эти сообщения своим игрокам, например, оповещать их об исправлениях ошибок или, возможно, информировать их о предстоящем продолжении. Независимо от того, для чего вы используете это, это невероятно полезная система, которая действительно может помочь вам использовать ваших поклонников.
Для получения дополнительной информации см. Это руководство .
Так много больше …
Несмотря на то, что мы многое рассмотрели в этом руководстве, API Kongregate способен сделать гораздо больше. К сожалению, мне пришлось бы написать небольшую книгу, чтобы рассмотреть все функции, особенно те, которые полезны для сетевых MMO. Если вам интересно узнать, какие еще функции предлагает API, я рекомендую посетить Центр разработчиков Kongregate для получения дополнительной информации.
Теперь, когда вы знаете, как настроить Kongregate API, я настоятельно рекомендую вам добавить его во все ваши будущие игры; если вам повезет, вы можете даже получить некоторые значки, и тогда начнется настоящее веселье.