Gamiphy SDKs

Introduction

Gamiphy is a user engagement and retention platform which offers clients the tools to engage, reach out and retain users, Gamiphy offers clients an all-inclusive gamification service with a variety of features including loyalty programs, branded games, quizzes and playable apps, basically anything to keep users engaged and coming back.

This document contains all the needed information to integrate the services that is provided by Gamiphy, focusing mainly on both Gamibot ( the loyalty program) and Gamistore ( the mini games).

Creating Gamiphy Account

details about the dashboard, how to signup, and link to documents

Installation

Gamibot and Gamistore are available as a javascript library that you can install on your application and integrate with using the javascript package manager npm, or a static script injection in code.

Gamibot

Getting Started

Step 1: Gamibot Initialization

Gamibot.init(<botId>, <options>)

| Name | Type| Description| | :--- | :--- |:----------- | | botId | String | Your gamiphy bot id, you can get the bot id from your account at Gamiphy in the dashboard, within the account settings | | options | object | Gamiphy bot options |

Kindly see more details about the options below.

| Name | Type | Description| | :--- | :--- | :----------- | | onAuthTrigger [Required] | Function: (isSignUp: boolean) => {} | As Gamibot is accessible for anonymous users, you can specify where to redirect these users to do sign-up/login whenever they are trying to do a specific task, Gamibot will call the methods you specify here as options. isSignUp is a flag available for you so you can know where to redirect the users, to the signup form or the login form according to your needs. | user [Optional] | object, null by default | {name: String, email: String, avatar: String, hash: String}, refer to Register users section below to get more details about the hash parameter. you only need to pass the users in case they are logged in. | withWidget [Optional] | boolean, true by default | Indicator to generate the bot widget, Gamibot SDK will help you show the widget of the bot from the SDK according to the configurations you did using Gamiphy dashboard account. | | language [Optional] | String, en by default | The language you want to use in the bot. Use ISO 639-1 codes | | isOpen [Optional] | boolean, false by default | Indicator to show the bot and open it by default once its initialized, recommended value is false until you need a special case of integration. |

Registering your users

You can register your users and communicate to Gamibot by calling the following method and passing the user data.

Gamibot.login({
	name: <name>, // Your user name. [Required]
	email: <email>, // You user email. [Required]
	avatar: <avatar>, // Your user avatar url. [Optional]
	hash: <hash> // Generated HMAC 
})

| Name | Type| Description| | :--- | :--- |:----------- | | name [Required] | String | user name| | email [Required] | String | user email | | avatar [Optional] | String, null by default | Your user avatar URL, your users will be able to change the avatar later in the bot if you don't have it. | | hash [Required] | String | Generated HMAC, Identity Verification, it helps to make sure that conversations/users between your application and Gamibot are kept private and that one user can't impersonate another. Identity Verification works by using a server side generated HMAC (hash based message authentication code), using SHA256, on the user�s email and name. |

Logout users

When users want to log out of your app, simply call logout like so:

Gamibot.logout();

Gamibot still showing for anonymous

As Gamibot is accessible for anonymous users, you can specify where to redirect these users to do sign-up/login whenever they are trying to do a specific task, Gamibot will call the methods you specify here. isSignUp is a flag available for you so you can know where to redirect the users, to the signup form or the login form according to your needs.

Gamibot.init(<botId>, {
	onAuthTrigger((isSignUp) => {
		if(isSignUp) {
			//Add redirect to sign up code
			//e.x. window.location.href = '/sign-up' in web
		} else {
			//Add redirect to login code
			//e.x. window.location.href = '/login' in web
		}
	})
})

Showing the bot If you selected the option withWidget in the init method as false, that means you need to handle showing, and closing the bot by calling the following methods:

Open Gamibot

Gamibot.open() // will open Gamibot

Close Gamibot

Gamibot.close() // will close Gamibot

Tasks and events

As you will have a Gamiphy account where you can access the dashboard and design the user journey in addition to several configurations, you will need to complete the integration according to the selected configs in the dashboard, for example when you are going to add a task, you will be asked to fill in the action name and the event name.

Gamibot will fire an action whenever the user trying to do a specific task in the bot so you can handle the business logic in your application, the following method onTaskTrigger will be called, and you will be receiving the action name you specified in the dashboard as a parameter, you can perform your login the call back function shown below according to each action per task.

Gamibot.onTaskTrigger(<actionName>, () => {
	//Action name handler
	//e.x. Redirect to the page where you can do the task
})

In order to send back to the bot whenever the user did a specific task in your application, so Gamibot can consider that task as done, you will need to call the following method and pass the eventName as a parameter, eventName value is specified in the dashboard when you create your tasks.

Gamibot.taskDone(<eventName>)

| Name | Type| Description| | :--- | :--- |:----------- | | eventName| String | Event name added in the dashboard|

Handling user's redeem

The following method will be called whenever the user is trying to redeem his points from Gamibot, Gamibot will trigger this method and pass the reward details as an object to the method, you can inject your logic within the handler according to the reward config you specified in the dashboard.

Gamibot.onRedeemTrigger((reward) => {
	// On redeem handler
})

kindly note the fields of the reward object you will get as a parameter as described above.

| Name | Type| Description| | :--- | :--- |:----------- | | _id | String | The reward identifier| | type | String | discount, freeShipping, gift | | meritPoints | number | The points at which the user can redeem the reward | | options | object | In case of discount rewards it contains {type: 'percent' | 'fixed'} |

Whenever the user attempt to get the reward, and he actually did get the reward, you'll need to communicate that to Gamibot so that the user points will be updated. you can do so by calling the following method.

Gamibot.redeemDone(<rewardId>)

| Name | Type| Description| | :--- | :--- |:----------- | | rewardId| String | The reward identifier|