How to connect your game

Getting started with Connect for Web

Pointvoucher Connect provides a simple API for connecting your game to the Pointvoucher platform. You can prepare for this integration in three easy steps.

  • Contact Pointvoucher to obtain a unique Connect API key for your game.
  • Download the latest version of the script (which is not on npm just yet). The download link is in development 👀
  • Place the script somewhere in your game projects scripts folder.

The script declares a global object PvConnect that you can initialize with your game details and a callback function.

// import the script
document.head.append(
  Object.assign(document.createElement('script', {
    src: '/scripts/pointvoucher-connect.js',
    onload: myinit,
    async: true,
  })
));

function myinit() {

  // log any errors
  PvConnect.onError(e => console.error(e.message));

  // initialize Connect
  PvConnect.init({
    api_key: "eyJhbGciOiJIUzI1Ni...",
    app_name: "My Addictive Game",
    app_icon_url: "'data:image/png;base64,iVBORw0KGgoAAAAN...",
  }, () => {

    // trigger first action
    PvConnect.action(PvConnect.CONTEXT_TITLE_SCREEN);
  });
}

Once initialized, you can at any time invoke the action method to trigger a user facing notification message. The method takes a context string and an optional callback as arguments. CONTEXT_TITLE_SCREEN may for example trigger a notification that invites the user to join Pointvoucher.

PvConnect.action(PvConnect.CONTEXT_TITLE_SCREEN, () => {
  console.log(`Let's play!`);
});

If provided, the callback gets invoked as soon as the user is done interacting with Connect, for example when the user swipes the invitation away or when the signup process has been completed. The SDK may also decide, not to show a notification at this point in time, in which case the callback gets invoked immediately. Connect adapts its behavior to the following contexts.

CONTEXT_TITLE_SCREEN
Used before the user presses Play. A notification may advertise the integration with Pointvoucher and invite the user to sign up.
CONTEXT_LEVEL_COMPLETE
Used in between game levels or some equivalent break in active gameplay. A notification may display points earned.
CONTEXT_GAME_OVER
When the game ends, a notification may display points earned.

Remember that Connect may always decide, not to show a notification when the action method is called, for example when the user has accumulated zero voucher points since the last status update.

Pointvoucher supports all the latest browsers, but notably not Safari 10 or any version of Microsoft Edge released before 2020. The SDK itself will not throw exceptions in unsupported browsers. Instead, it will simply never display notifications and always execute your callback functions immediately. The Pointvoucher integration is in other words invisible to users of legacy browsers.

Firefox
Chrome
Edge 79+
Safari 11+

PvConnect

MethodParamsReturnsDescription
action
  • string context
  • Function callback
void

Instruct Connect to display an appropriate notification based on the given context. The optional callback is invoked when the notification gets dismissed or closes automatically.

init
  • Object config
  • Function callback
void

Initialize Connect whenever the user opens the game. The optional callback is invoked when initialization either succeeded or failed. Make sure to configure method onError to identify the cause of potential failure.

onError
  • Function callback
void

Get an angle on potential errors since Connect is otherwise designed to fail silently. The callback receives an object with a message property.

openAccount
  • Function callback
void

Open the user's account page via Pointvouchers website. The optional callback is invoked when the popup is closed.

openShop
  • Function callback
void

Open the voucher shop via Pointvouchers website. The optional callback is invoked when the popup is closed.