Advertisement
  1. Code
  2. Games

Uso de la API Kongregate en tus juegos Flash

Scroll to top
Read Time: 16 min

Spanish (Español) translation by Luis Chiabrera (you can also view the original English article)

Kongregate es uno de los portales de juegos Flash más grandes de la red, y tiene su propia API que puede integrarse en tus juegos (por lo que Kongregate incluso te recompensa financieramente). En este tutorial, le mostraré cómo implementar la API de Kongregate en sus juegos, y también entrar en detalles sobre de qué es capaz la API y por qué debería usarla.

(Tenga en cuenta que este tutorial supone que ya tiene una cuenta de Kongregate, si no lo tiene, cree una ahora).


Vista previa del resultado final

Echemos un vistazo a lo que la API nos permite hacer:

Medallas

Mensajes masivos

Mejores Puntajes

Hay otra gran razón para implementar la API ...


Paso 1: Vamos a motivarnos

Antes de sumergirnos en los aspectos técnicos de la implementación de la API de Kongregate, aumentemos un poco la atención y nos aseguremos de que realmente queremos implementarlo.

Hay muchas razones para implementar la API, pero para la mayoría de los desarrolladores, nada habla más fuerte que el dinero, y hay mucho de eso involucrado. Cuando subes tu juego a Kongregate, ganas automáticamente el 25% de todos los ingresos publicitarios generados por la página de tu juego.

Se pone mejor; si implementa su "API de estadísticas y desafíos", recibirá un 10% adicional. Finalmente, si su juego es exclusivo de Kongregate o patrocinado por ellos, recibirá un 15% adicional. Esto le da la oportunidad de ganar hasta el 50% de los ingresos publicitarios de su juego en Kongregate. Si te preguntas cuánto es eso, mira algunas de mis estadísticas personales:


Paso 2: configurando nuestro entorno de trabajo

Para este tutorial, usaremos FlashDevelop, un editor de código abierto gratuito (y sorprendente) para desarrolladores. Haremos todo en simples archivos .as, por lo que si desea seguir el uso de Flash IDE, no debería tener ningún problema. Si desea utilizar FlashDevelop y no está familiarizado con él, consulte esta excelente guía para principiantes de FlashDevelop para que comience con lo que consideraría el mejor editor de AS3 que existe.

Para comenzar, abra FlashDevelop, vaya a la pestaña Proyecto y seleccione "Nuevo proyecto". Desde aquí, seleccione "Proyecto AS3 con precarga". Alternativamente, puede tomar los archivos Preloader.as y Main.as desde la descarga de la fuente, y simplemente seguirlo.

Su archivo debe ser un archivo Main.as sin formato, así:

Nada de lo anterior debe ser nuevo para usted; si lo es, todo lo que necesita saber es que este archivo es el punto de entrada para nuestro programa, aquí es donde comienza todo. Si compila esto con FlashDevelop, debería obtener una pantalla blanca en blanco, sin errores de compilación.


Paso 3: conectemos

Antes de sumergirnos en todas las características geniales de la API, debemos asegurarnos de que tenemos la API en funcionamiento.

A diferencia de muchas API de patrocinadores, la API de Kongregate no es un conjunto independiente de archivos que necesitamos compilar con nuestro proyecto. La API está realmente almacenada en el servidor Kongregate, y la cargamos en tiempo de ejecución. Hay varias maneras de hacer esto en sus proyectos, pero por el bien de este tutorial, simplemente nos conectaremos dentro de nuestro Main.as, y guardaremos una referencia allí.

Para comenzar, copie el siguiente código en nuestro archivo Main.as justo debajo de las importaciones existentes:

Lo anterior son solo unas pocas importaciones simples que nos permitirán usar las clases necesarias para cargar en la API de Kongregate.

A continuación, agregaremos una variable para almacenar nuestra referencia a la API de Kongregate. Continúe y agregue el siguiente derecho sobre el constructor de nuestro archivo Main.as.

Tenga en cuenta que el tipo de datos de nuestra variable kongregate es *. Si no está familiarizado con esto, simplemente le estamos diciendo al compilador que la variable kongregate aceptará cualquier tipo de datos, al igual que un comodín.

(Además, tenga en cuenta que en un juego real le gustaría almacenar su referencia a la API en algún lugar al que tenga acceso todo su proyecto, como una const. Pública estática. Esta referencia es necesaria para que pueda usar la API desde cualquier lugar en su proyecto, para cualquier propósito, en lugar de solo en el archivo Main.as cuando se inicia por primera vez).

Esta próxima pieza de código estará contenida en una función personalizada con el nombre de initKongregateAPI (). Esto no es realmente necesario, pero prefiero encapsular ideas al escribir código, ya que ayuda a mantener el código legible y fácil de trabajar.

Continúe y agregue esta función debajo de la función init en Main.as.

Si bien puede parecer mucho código, en realidad no es mucho, y con los comentarios, es bastante fácil de seguir.

Como verás, en la primera parte estamos creando una variable para almacenar la ruta API desde FlashVars (si no sabes cuáles son, búscalos rápidamente, son una gran cosa para entender)

En el segundo fragmento, determinamos si el archivo SWF se encuentra en el sitio web de Kongregate o si se está ejecutando localmente, y asignamos la información adecuada a la variable apiPath.

A continuación, damos acceso a la API al SWF, con una simple llamada a security.allowDomain, donde pasamos el apiPath como parámetro.

Luego creamos un nuevo objeto URLRequest, que obtiene el apiPath pasado al constructor, un nuevo objeto Loader, y agrega un detector de eventos para el cargador que llamará a loadComplete cuando haya terminado.

Por último, llamamos a loader.load y pasamos en nuestra solicitud (el objeto URLRequest recién creado, que contiene el apiPath de la API de Kongregate). Si entiendes lo que acaba de pasar, genial; si no, no te preocupes, ya que no tendrás que volver a tocar esto.

¡No te olvides de llamarlo!

Ahora que se creó la función initKongregateAPI, y contiene todo el código de conexión, ¡probablemente deberíamos asegurarnos de que esta función sea realmente llamada! Simplemente regrese a la función init que nuestro archivo Main.as ya contenía, y agregue una llamada a la función initKongregateAPI después de la línea que la línea de "punto de entrada", como tal,

Finalmente, necesitamos agregar esa función loadComplete, que se llamará cuando el evento COMPLETE se active desde nuestro código anterior. Agregue esta función debajo de la función initKongregateAPI en Main.as.

El código anterior es súper simple; vamos a repasarlo. Comenzamos guardando una referencia a la API de Kongregate. Como puede ver, estamos haciendo referencia a la API Kongregate a través del parámetro de evento transmitido en pasado, a través de event.target.content, lo suficientemente simple.

Ahora todo lo que tenemos que hacer es conectar, y nuestro SWF está listo para funcionar. Como puede ver, nos conectamos llamando al método kongregate.services.connect. No se requieren argumentos.

Si bien eso puede haber parecido mucho trabajo, realmente no fue así. Simplemente repasé el proceso de conexión con mucho detalle, para que pueda entender cómo estamos realmente obteniendo acceso a la API, en lugar de solo tener ese acceso y usarlo. Ahora que lo entiende, puede usar todo lo anterior como código repetitivo.


Paso 4: la API de estadísticas y desafíos

Ahora que estamos conectados, podemos echar un vistazo a la característica más importante de toda la API: la porción de estadísticas y desafíos. Esta API envía estadísticas relacionadas con el jugador al servidor de Kongregate, lo que permite una serie de cosas.

En primer lugar, esta es la forma más básica de permitir a los usuarios competir por puntajes altos en Kongregate. Con la API integrada, la barra lateral de Kongregate incluirá una nueva pestaña con la etiqueta "LOGROS", que se encuentra junto a la pestaña "CHAT". Los jugadores pueden ver tablas de clasificación para cualquier estadística que envíes a los servidores, que podría ser cualquier cosa, desde un puntaje básico alto hasta el número total de enemigos derrotados.

El segundo y mucho más importante uso es permitir que Kongregate use las estadísticas que envía para crear "insignias" para sus juegos. Las insignias son una parte central de la experiencia de usuario de Kongregate y se parecen mucho a los sistemas de logros en plataformas como Xbox LIVE.

La mejor parte de tener insignias agregadas a tu juego es que tu juego aparecerá brevemente, lo que aumentará en gran medida la cantidad de visitas que obtienes y, por lo tanto, aumentará enormemente los ingresos publicitarios. Incluso después de que su juego quede fuera del centro de atención, todos los juegos con insignia en Kongregate continúan recibiendo incrementos en las vistas de los juegos normales, lo que le brinda una excelente fuente de ingresos de larga cola.

Tenga en cuenta que las credenciales no las agregan los desarrolladores, sino que las crea el personal de Kongregate. Necesitarás un juego de alta calificación para ser seleccionado, pero también necesitarás configurar la API, ¡así que librémonos de la mitad de la batalla!


Paso 5: preparación de back-end

Para usar realmente las estadísticas que enviaremos, Kongregate primero nos obliga a informar a su servidor qué información debe estar preparada para recibir de nosotros.

Para hacer esto, simplemente vamos a la página de Estadísticas para nuestro juego en el sitio web de Kongregate. Puede encontrarla en la página "Editar juego" o agregando / estadísticas al final de la URL de su juego (por ejemplo, http://www.kongregate.com/games/EpicShadow/pixel-purge/statistics). Para este tutorial, simplemente cargaremos nuestro SWF de prueba como el "juego".

Antes de agregar cualquier estadística a la API de estadísticas y desafíos, primero debemos entender los cuatro tipos de estadísticas que se pueden usar y las reglas a las que están sujetas. Los valores deben ser positivos, y deben ser enteros positivos. Los cuatro tipos son los siguientes:

  • Máx .: El valor en el servidor será reemplazado si el nuevo valor es más alto que el valor almacenado. Por ejemplo, un puntaje alto de 152,000 reemplazaría un antiguo puntaje alto de 120,000.
  • Min: el valor en el servidor será reemplazado si el nuevo valor es menor que el valor almacenado. Por ejemplo, en un juego de carreras, un tiempo de vuelta de 31 segundos reemplazaría un valor anterior de 35.
  • Agregar: el nuevo valor se agregará al valor almacenado. Un uso común de esto sería el total de enemigos derrotados, muertes de jugadores, etc. Demasiadas solicitudes al servidor pueden dar como resultado datos inexactos, por lo que se aconseja que los datos solo se envíen a granel, como cuando se completa un nivel o cuando el jugador muere.
  • Reemplazar: el nuevo valor reemplazará el valor almacenado sin importar qué. Esto se puede usar para varias cosas, como el tiempo promedio de supervivencia o la clasificación de jugadores.

Saber cuál de los tipos anteriores necesitas usar para cada una de tus estadísticas de juego es extremadamente importante, así que asegúrate de familiarizarte con la lista anterior. Obviamente, querrás una lista de estadísticas que quieras que tu juego envíe a Kongregate, así que asegúrate de tenerlas preparadas antes de sumergirte en el siguiente paso cuando realmente envíes un juego.

Por el bien de este tutorial, simplemente usaremos las siguientes estadísticas:

  • Clics totales (Agregar)
  • Clicks Máximos(Max)
  • Última X (Reemplazar)

Una vez que su lista esté preparada, diríjase a la página de estadísticas de su juego e ingrese los datos requeridos. Una vez que el trabajo de back-end se realiza en la página de estadísticas, el juego estará listo para enviar datos al servidor de Kongregate.


Paso 6: cómo enviar estadísticas

Para enviar datos al servidor, simplemente llamamos a la función "enviar", que se ve así:

Como puede ver, la función toma dos parámetros:

  • statName es el nombre de tu estadística. Es muy importante que el String passed sea idéntico (distinga entre mayúsculas y minúsculas) al nombre de la estadística que enumeró en el paso anterior al preparar el servidor para manejar sus estadísticas.
  • value es el valor numérico real que se pasará. Aunque el tipo de datos es Número, recuerde que su valor debe ser un entero positivo.

Para llamar a esta función en su juego, simplemente haga lo siguiente:

Aunque teníamos cuatro tipos diferentes de estadísticas que podríamos enviar, esta función solo envía el valor; el servidor mismo verá la información que proporcionamos en el paso anterior para determinar cómo tratar los datos entrantes. Es tan simple como eso; ahora sabemos cómo enviar datos al servidor.


Paso 7: preparar su proyecto para enviar estadísticas

Ahora que hemos preparado el back-end en el sitio web Kongregate, y ahora sabemos cómo enviar datos, demos un vistazo a este proyecto.

Lo primero que debemos hacer es agregar un código a nuestro proyecto para enviar nuestras estadísticas. Como lo más fácil de rastrear es la entrada del mouse, he elegido las estadísticas relacionadas con el mouse. Como viste en nuestro paso anterior, elegí Max Clicks, Total Clicks y Last X.

Max Clicks será el puntaje más alto de la cantidad de veces que hacemos clic en un solo juego, para demostrar el tipo Max; Los clics totales serán el total de todos los clics que hemos hecho, para demostrar el tipo Agregar; y la última X será la posición x de nuestro clic más reciente para demostrar el tipo Reemplazar.

Para rastrear los clics de nuestro mouse, necesitaremos importar la clase MouseEvent. Regrese a Main.as y agregue lo siguiente a sus importaciones:

Ahora vamos a necesitar agregar una variable para nuestra estadística Max Clicks, para hacer un seguimiento de la cantidad total de clics por sesión de juego. Justo debajo de donde agregamos la variable de referencia kongregate (del tipo de datos *), agregue lo siguiente:

Vamos a necesitar un oyente de eventos para escuchar nuestros relojes, así que lo agregaremos ahora. En la función init, justo debajo de la llamada para iniciar la API de Kongregate, agregue lo siguiente:

Como puede ver en el código anterior, la función llamada siempre que se llame al evento que activó se llama clicked. Avancemos y creemos esa función. Agregue lo siguiente debajo de su función loadComplete:

Todo lo que hacemos aquí es incrementar la variable maxClicks en 1 y luego enviar toda la información requerida al servidor Kongregate. Esto agregará 1 a la estadística de Clics totales, enviará la variable actual de maxClicks al servidor, que luego determinará si es más alta que el valor anterior y la reemplazará si es así, y enviará la posición x de nuestro clic anterior, que automáticamente Reemplace el valor anterior.

Nuestro SWF puede ser solo una pantalla en blanco, pero están sucediendo muchas cosas, y estamos a punto de verlo en acción. Asegúrese de compilar el proyecto antes de continuar.


Paso 8: probando nuestro proyecto

Ahora es el momento de cargar nuestro proyecto y verlo en acción.

Regrese al sitio web de Kongregate, diríjase a la página del juego y cargue la versión final de nuestro proyecto. Una vez que haya cargado el proyecto, se lo llevará a una pantalla de vista previa, donde podemos probar nuestro proyecto antes de publicarlo. Para ahorrarle al personal de Kongregate mucho tiempo y energía, haga un favor a todos y no presione publicar en su SWF de prueba. (Si estás trabajando en un juego real, adelante, pero por el bien de este tutorial no publicaremos este proyecto).

Una vez que estés en la página de prueba, dale al juego unos pocos clics. Actualiza la página, y ahora deberías ver que hay una pestaña "PUNTUACIONES ALTAS" al lado de la pestaña "CHAT" y "GAME". Si ha hecho todo correctamente hasta este punto, debe tener un cuadro desplegable que actualmente dice "Última X" que también contiene "Clic máx." Y "Clics totales". Tenga en cuenta que hacer clic rápidamente dará como resultado estadísticas inexactas, ya que el servidor no puede mantenerse al día con todas las solicitudes, por lo tanto, haga clic despacio para obtener los mejores resultados. Esta es la razón por la que aconsejé antes que envíe grandes lotes de datos al morir o al completar el nivel, cuando sea posible.

Bueno, ahí lo tienes: ahora tienes la parte más importante de la API Kongregate en funcionamiento. Si su proyecto no está funcionando en este punto, asegúrese de que sus nombres de dominio de fondo Kongregate estén escritos exactamente como están en su función de envío (distingue entre mayúsculas y minúsculas) ya que ese suele ser el problema.

También puede encontrar el código completo en la carpeta de archivos final en la descarga de la fuente, así que compare su código con eso si todavía tiene problemas.


Paso 9: Comunicaciones de mensajes masivos

¿Alguna vez lanzó un juego, y luego, realmente quería llegar a todos tus fanáticos? Bueno, con la API Kongregate, puedes hacer eso, al menos, para todos tus fans de Kongregate.

Existen algunas restricciones sobre quién puede hacer esto, pero estas restricciones son muy beneficiosas tanto para los desarrolladores como para los jugadores. Para calificar, su juego debe recibir una calificación de 3.75 o superior, y tener al menos 10k juegos de juegos.

Puede enviar un mensaje de "jugadores activos" como máximo una vez cada siete días. Estos mensajes se enviarán a cualquier jugador que haya jugado el juego al menos tres veces, y al menos una vez en los últimos diez días.

Puede enviar un mensaje de "jugadores inactivos" como máximo una vez cada 30 días. Estos mensajes serán recibidos por cualquier jugador que haya jugado al menos cinco veces en total, pero no en los últimos diez días.

Hay muchas razones para enviar estos mensajes a sus jugadores, como alertarlos sobre correcciones de errores o tal vez informarles de una próxima secuela. Independientemente de para qué use esto, es un sistema increíblemente útil que realmente puede ayudarlo a apalancar a sus admiradores.

Para obtener más información, consulte esta guía.


Mucho más...

Si bien hemos cubierto mucho en este tutorial, la API Kongregate es capaz de hacer mucho más. Desgraciadamente, tendría que escribir un pequeño libro para revisar todas las características, especialmente las que son útiles para los MMO basados en la web. Si está interesado en verificar qué otras características tiene la API para ofrecer, le recomiendo que visite Kongregate Developers Center para obtener más información.

Ahora que sabe cómo poner en marcha la API de Kongregate, le recomiendo que la agregue a todos sus juegos futuros; si tienes suerte, incluso puedes obtener algunas insignias, y ahí es cuando comienza la verdadera diversión.

Advertisement
Did you find this post useful?
Want a weekly email summary?
Subscribe below and we’ll send you a weekly email summary of all new Code tutorials. Never miss out on learning about the next big thing.
Advertisement
Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.