Jovo Community Plugin - Badgerific

Overview

This plugin for the Jovo Framework allows you to add badges and achievements to your games and apps using the Badgerific library.

Supports

Jovo Framework 4.x
Platforms: any (alexa, googleAssistant, core, web, etc.)
Requires a Database Integration for user data storage.

This plugin is registered as part of the dialogue.start middleware and is meant to be used in component handlers and hooks after that point. By this time the user's data is loaded from the configured database integration.

To use the callbacks for $badges, add a hook for the after.dialogue.start middleware. See Callbacks.

The badges data is set on this.$user.data during the before.response.start middleware so that it will be auto saved to storage on response.start.

Install

Install the plugin into your Jovo project:

npm install @jovo-community/plugin-badgerific --save

app.js:

const { BadgerificPlugin, BadgerificInitData } = require('@jovo-community/plugin-badgerific');
const badgeRules = require('./badgeRules.json');

const app = new App({
  plugins: [
    new BadgerificPlugin({
      onInit: (jovo: Jovo) => {
        console.log('BadgerificPlugin:onInit');
        return {
          timeZone: 'America/Phoenix',
          rules: badgeRules,
        } as BadgerificInitData;
      },
    })    
  ],
});

app.ts:

import { BadgerificPlugin, BadgerificInitData } from '@jovo-community/plugin-badgerific';
import badgeRules from './badgeRules.json';

const app = new App({
  plugins: [
    new BadgerificPlugin({
      onInit: (jovo: Jovo) => {
        console.log('BadgerificPlugin:onInit');
        return {
          timeZone: 'America/Phoenix',
          rules: badgeRules,
        } as BadgerificInitData;
      },
    })    
  ],
});

Configuration

The plugin has the following values:

Property	Type	Default	Description
userStorageKey	string	"badgerific"	Required. The key is used with `this.$user.data` to store the badges data.
autoSession	boolean	true	Required. When `true`, automatically calls `$badges.startSession()` and `$badges.endSession()` to match the platform session.
onInit	function		Required. Allows you to set the `timeZone` and `rules` and is called during the `dialogue.start` middleware. A callback allows you to execute code to set the values. For example, you can use the Time Zone Plugin to determine the timezone or get the rules from a CMS plugin.

Usage

This plugin allows for easier usage of the Badgerific library with Jovo v4 by using the this.$badges.

Create Rules

Rules are contained in a JSON array:

[
  {
      "id": "b01",
      "description": "First game started",
      "active": true,
      "max": 1,
      "updatePeriod": "GLOBAL",
      "condition": "system.isNewGame && system.lifetimeGames == 1"
  }
]

Learn more about creating rules here. A list of sample rules can be found here.

Custom Properties

Set custom properties in handlers and hooks like this:

this.$badges.setValue('prop1', 1);
this.$badges.setValue('prop2', true);
this.$badges.setValue('prop3', 'test');

this.$badges.addValue('prop4');
this.$badges.addValue('prop5', 1);
this.$badges.addValue('prop6', 2);

this.$badges.subtractValue('prop7');
this.$badges.subtractValue('prop8', 1);
this.$badges.subtractValue('prop9', 2);

Get Earned Badges

Examples of getting list of earned badges:

// changing a property value
const earned = this.$badges.setValue('prop1', 'test');
const earned = this.$badges.addValue('prop2');
const earned = this.$badges.subtractValue('prop3');

// start/end session
const earned = this.$badges.startSession('prop3');
const earned = this.$badges.endSession('prop3');

// start/end game
const earned = this.$badges.startGame('prop3');
const earned = this.$badges.endGame('prop3', GameEndReason.Win);

// all badges earned
const earned = this.$badges.getEarnedBadges();

// all or current year, month, week, day, hour, session, game
const earned = this.$badges.getEarnedBadges(Period.Game); 

// since a given UTC time
const earned = this.$badges.getEarnedBadgesSince('2022-07-11T04:45:52.815Z');

// since a bookmark
this.$badges.setBookmark('mark1');
const earned = this.$badges.getEarnedBadgesSinceBookmark('mark1');

Callbacks

Badgerific has callbacks that you can use. Define these in app.js or app.ts with a hook. The best middleware to do this is after.dialogue.start:

import { GameEndReason, ReadonlyBadgeProperties, ReadonlyEarnedBadge } from 'badgerific';

app.hook('after.dialogue.start', (jovo: Jovo): void => {
  
  // onBadgeEarned
  jovo.$badges.onBadgeEarned = (badge: ReadonlyEarnedBadge) => {
    console.log('Badgerific:onBadgeEarned');
  };

  // onNewTimePeriod
  jovo.$badges.onNewTimePeriod = (
    props: ReadonlyBadgeProperties,
    systemProps: ReadonlyBadgeProperties,
  ) => {
    console.log('Badgerific:onNewTimePeriod');

    if (systemProps.isNewDay) {
      jovo.$badges.setValue('dailyWins', 0, true);
    }
  };

  // onSessionStart
  jovo.$badges.onSessionStart = (
    props: ReadonlyBadgeProperties,
    systemProps: ReadonlyBadgeProperties
  ) => {
    console.log('Badgerific:onSessionStart');
  };

  // onSessionEnd
  jovo.$badges.onSessionEnd = (
    props: ReadonlyBadgeProperties,
    systemProps: ReadonlyBadgeProperties
  ) => {
    console.log('Badgerific:onSessionEnd');
  };

  // onGameStart
  jovo.$badges.onGameStart = (
    props: ReadonlyBadgeProperties,
    systemProps: ReadonlyBadgeProperties
  ) => {
    console.log('Badgerific:onGameStart');
  };
  
  // onGameEnd
  jovo.$badges.onGameEnd = (
    props: ReadonlyBadgeProperties,
    systemProps: ReadonlyBadgeProperties,
    reason: GameEndReason,
  ) => {
    console.log('Badgerific:onGameEnd');

    if (reason === GameEndReason.Win) {
      jovo.$badges.addValue('dailyWins', 1, true);
    }
  };
});

Jovo Debugger

If using the Jovo Debugger, you must add $badges to the list of properties the debugger ignores:

// app.dev.ts

new JovoDebugger({
  ignoredProperties: ['$app', '$handleRequest', '$platform', '$badges'],
}),

License

MIT