@jovo-community/plugin-badgerific
v1.0.1
Published
A Jovo Framework plugin for badges and achievements using the Badgerific library.
Downloads
7
Readme
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.
RIDR Lifecycle
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
Register the plugin in:
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