simplegoals v0.3.1

SimpleGoals allows you to quickly and easily create achievements your users can accomplish — add intriguing game elements to your website.

And even more: CloudStorage allows you to keep users' achievements persistent across different browsers and devices. It only takes a couple of minutes to add new options to get everything ready.

• How it works?
• Installation
  • CDN (Easiest)
  • Download files
  • Webpack or Browserify (Advanced)
• Usage
  • Initializing
  • Unlock achievements
  • Show all achievements
  • Options
• CloudStorage
• Development
• License

How does it work?

• Create a list of goals your users can achieve. 🏆
• Decide when each achievement is unlocked (e.g. on a button click, or when a special page was opened) ⏰
• Add a small JS snippet to your website. 👩‍💻
• Tada! 🎉

Installation

There are several ways to get started with SimpleGoals. You can use:

CDN (Easiest)

Just add this line to HTML code it before the closing </body> element.

<script type="text/javascript" src="https://static.simplegoals.co/0.3.1/simplegoals-styles-included.min.js"></script>

And you're ready to use SimpleGoals!

If you're going to update styles of SimpleGoals, you might want to load JS and styles separately:

// Before closing </head> element
<link rel="stylesheet" href="https://static.simplegoals.co/0.3.1/simplegoals.min.css">
// Before closing </body> element
<script type="text/javascript" src="https://static.simplegoals.co/0.3.1/simplegoals.min.js"></script>

Download files

You can download SimpleGoals files from https://static.simplegoals.co/0.3.1/simplegoals.zip and add them to your project directory

Then load them in HTML:

// Before closing </head> element
<link rel="stylesheet" href="simplegoals.min.css">
// Before closing </body> element
<script type="text/javascript" src="simplegoals.min.js"></script>

Webpack or Browserify (Advanced)

Add package:

// With npm
npm install simplegoals --save

// With yarn
yarn add simplegoals

Load SimpleGoals in your JS code

// Webpack
import 'simplegoals/dist/simplegoals.min.css'
import SimpleGoals from 'simplegoals';

// Browserify
require 'simplegoals/dist/simplegoals.min.css'
var SimpleGoals = require('simplegoals');

Usage

Using SimpleGoals is fast and easy!

Initializing

To use SimpleGoals you need to initialize it:

// Define a list of all available goals (Example)
var goals = {
  explorer: {
    name: "Curious Explorer",
    description: "Scroll through half of the page"
  },
  secret: {
    name: "Lucky Digger",
    description: "Find a secret button"
  }
}

// Initialize SimpleGoals when a page is loaded
window.addEventListener('load', function() {
  SimpleGoals.init({
    goals: goals
  })
});

You can check out all available options in the Options section

Unlock achievements

There are two ways to unlock goals.

• You can add data-simplegoals-unlock="key_of_goal" attribute to any button. When a user clicks this button, the goals will be unlocked and achievement will appear.

  <a data-simplegoals-unlock="secret" href="#">I'm a secret button</a>

• You can call SimpleGoals.unlock("key_of_goal") method at any time.

SimpleGoals.unlock("explorer")

Example:

// Scroll through half of the page
if (document.body.scrollTop > document.body.scrollHeight / 2) {
  SimpleGoals.unlock("explorer")
}

Each goal can be unlocked and shown only once.

Show all achievements

There are also two ways to show all achievements.

• You can add data-simplegoals-overview="true" attribute to any button. When user click this button, the list of all achievements will be shown. Example:

  <a data-simplegoals-overview="true" href="#">Show all achievements</a>

• You can call SimpleGoals.showOverview() method at any time.

  SimpleGoals.showOverview()

  Example:

  // Scroll through half of the page
  if (document.body.scrollTop > document.body.scrollHeight / 2) {
    SimpleGoals.showOverview()
  }

Options

Theme options

Example:

SimpleGoals.init({
  goals: goals,
  onGoalUnlock: function(goalKey){ console.log(goalKey) },
  theme: {
    fontFamily: 'Arial, Helvetica, sans-serif',
    background: '#ffffff',
    primary: '#38b2ac',
    title: '#000000',
    subtitle: '#718096'
  }
  timeout: 10000,
  useCloudStorage: true,
  appId: "f072c862-4f88-4be9-a86e-521e4a282e68",
  user: {
    uid: "magician#3123936",
    email: "harry@hogwarts.com",
    name: "Harry Potter"=
  }
})

CloudStorage

CloudStorage allows you to keep users' achievements persistent across different browsers and devices. It only takes a couple of minutes to add new options to get everything ready.

There are two little steps you need to do:

• Go to https://api.simplegoals.co/projects/new and get an appId that you can use. It's might be useful to get new appId for each of your environments: test, staging, production and so on.
• Add new options to SimpleGoals.init() call:

  SimpleGoals.init({
   goals: goals,
   useCloudStorage: true, // Required for CloudStorage
   appId: "yourAppId", // appId that you just got
   user: { // Information about User
     uid: "magician#3123936", // Optional, but either UID or email should be present
     email: "harry@hogwarts.com", // Optional, but either UID or email should be present
     name: "Harry Potter" // Optional
   }
  })

  UID is any unique identifier for a user.

Either UID or email should be present for user params.

Note: It works only for logged in users

Note: When users first time converts from a guest to a logged in user, all their achievements are saved in CloudStorage

Development

First of all, thank you for making SimpleGoals better!

All source files are in src folder.

To install all dependecies run:

npm install
// or
yarn install

To run local environment run:

npm run playground
// or
yarn playground

Playground will be available at http://localhost:8080

To build production-ready bundle run:

npm run build
// or
yarn build

License

This project is licensed under MIT license.