Skip to main content

Trigger Events

One of the key features of Gamanza Player Engagement Platform (PEP), is the capability to allow operators/integrators to send Events. These events can dispatch a series of triggers, for the CRM, giving full control to the Admin operator to use the data contained in the trigger to perform a series of configurations and customizations and even to create custom triggers.

You can find the Trigger Events API Specification here Process trigger action, but in this chapter, we are going to explain in detail how trigger events work with examples, and unwrap their capabilities.

drawdraw

Trigger Event Structure​

The trigger event is conformed by the following payload properties and options:

  • eventName: string Trigger event identifier. e.g: reset-password, is important to use a convention: it could be middle dashes or low dashes to separate words.
  • playerId: string The player unique identifier that performs an activity in the operators side/platform.
  • version: string [optional] its purpose is to track changes. The default value is v1.
  • eventDate: date-string Date and time when the event has been launched.
  • payload: array Is a list of key/type/value structured objects that contains information for the event.
  • external: object Refers to an event that can trigger a CRM transactional campaign that should be delivered to an external person. By "external" we mean that it is not registered in the operators system and therefore no information is in PEP.
  • delay.duration: string ISO-8601 Defines a delay for PEP before starting to process the event. Useful when you need to dispatch a CRM transactional campaign, and you need to wait some time before sending it.
  • keepCounter: This option enables PEP to create two special properties for the player: last execution date, and execution count. These properties are created following this convention:
    • for last execution [last][EventNameInCamelCase][Date] for example for reset-password: lastResetPasswordDate
    • for counters [eventNameInCamelCase][Count] for example for reset-password: resetPasswordCount
warning
  • The event name should be meaningful to easily identify it in the platform.
  • Please, make sure to keep consistency of the event name, the platform uses this value as a unique identifier for the event. If this name changes, a new event will be created and all things related to the previous event will stay as they are. This means that Admin Operators are forced to manually link CRM Transactional Campaigns or Gamification Contribution rules again.

Payload Property Structure​

The payload property contains relevant information for the event. PEP can use this information to dispatch transactional campaigns. The payload is an array of objects with the following structure:

  • key: unique property name, can be any valid programming language variable format: CamelCase, PascalCase, snake_case, kebab-case, UPPER_CASE. Internally the PEP platform creates a proper human-readable display name to easily interact with this data in the PEP Admin.
  • type: value data type used by PEP to analyse and allow configurations over the event. Allowed data types:
    • string: represents a sequence of characters.
    • number: represents a numerical data value, including integers and floating-point numbers
    • date: represents a date data type expressed in RFC 3339 format
    • boolean: represents a binary value indicating either true or false
    • enum: represents a data type that can be enumerable, like status, tags, etc
  • value: the actual value. The value of each property should be defined in the string representation.
note

You can send as many properties as you need.

External Property Structure​

The external property should be used, for example, to trigger a transactional campaign to be delivered to an external person. By definition, PEP can only send communications through the CRM module and only to the players registered in PEP, for more details check Player Information. But let's say for example that you have a built-in refer a friend in your website, and you need to send an email or sms to this third party future user in real time, the external property allows you to define the minimum required information for the CRM to send this communication.

Let's see the properties:

  • isExternal: Flag to determine if the event is targeted towards an external user outside the platform. If the player doesn't exist because you need to send an event prior to sending the player information to PEP, set this value to false or omit the property in the request. Default: False
  • channel: Defines the method of contacting the external user. Available options: sms or email
  • contactValue: The value of this field is determined by the channel. e.g: [email protected] | +41 78 123 45 67
  • language: Language used to send the communication (Language Code ISO code 639-1) example: (EN or ES)

Usage Examples​

Now let's see through example how event triggers work for the CRM:

Basic usage​

Imagine that you want to email every player that sets a score to a video only if the score is greater than or equal to 7. Easy... First you need to make sure to send a trigger event to PEP as follows:

The player 00000000-0000-0000-0000-000000000001 wants to set a video view and place a reaction/feeling about the video:

Show me the code!
import axios from 'axios';

const axiosInstance = axios.create(...);

/**
 * Dynamically process trigger actions based on events received by player
 * for playerID: 00000000-0000-0000-0000-000000000001
 * API Spec: @url: https://docs.gamanzaengage.com/docs-api/platform-rx-api/crm/trigger-campaign/trigger-controller-process-trigger-action
 */
await this.axiosInstance.post(
'https://customer-domain.gamanzaengage.com/rx-api/campaign/v1/trigger/send',
{
    "playerId": "00000000-0000-0000-0000-000000000001",
	"eventName": "video-view",
	"version": "1",
	"eventDate": "2024-03-26T20:59:32.000Z",
	"payload": [
		{
			"key": "url",
			"type": "string",
			"value": "https://www.youtube.com/watch?v=5BsFnk83NMI&ab_channel=KnightRiderOfficial"
		},
		{
			"key": "score",
			"type": "number",
			"value": "10"
		},
		{
			"key": "feeling",
			"type": "enum",
			"value": "1",
			"options": [
				{
					"key": "nostalgic",
					"value": "1"
				},
				{
					"key": "action",
					"value": "2"
				},
				{
					"key": "drama",
					"value": "3"
				},
				{
					"key": "excited",
					"value": "4"
				}
			]
		}
	],
	"keepCounter": true
});

info

The value of each property should be defined in the string representation.

warning

Take into consideration that type validations are performed to ensure data consistency. For example, if you define the score as a number but you send a string value not numerical or a non valid numeric string value, the request will end with an HTTP status code 400:

{
    "message": "Bad Request Exception",
    "request": {...}
    "details": {
        "faultCode": 400,
        "fields": [
            {
                "field": "1.value",
                "error": "value must be a number string"
            }
        ]
    }
}

In this basic example, as you can see, the event information is processed and categorized by PEP and is available to be used by the CRM Campaign module, later to create a transactional campaign.

info

A Transactional Campaign for PEP, is any CRM Campaign that is dispatched through trigger events.

All this happens automatically in real-time. PEP is a system based on reactive data streaming, this means that the system is designed to operate and make decisions based on up-to-the-minute data, that is transmitted and processed reactively, as it is generated.

Now let's explain some details of this event:

As you saw in the video, the event doesn't exist in PEP. Once PEP receives the first event, the platform tries to resolve and analyze the information contained in the event to extract all the metadata based on the properties defined in the payload and provide enough context to the Casino Admin Operators to create operations based on the event information.

Please notice that the settings property keepCounter is defined as true. This automatically generates two properties in the player:

Trigger events - auto counter propertiesTrigger events - auto counter properties

Tracking updates​

Continuing with our previous example, let's say that another player 00000000-0000-0000-0000-000000000002 watches a video and sets a different reaction/feeling. But additionally, you want to send/expose another property in the event, called viewDurationInSeconds to add a special filter to send a Bonus to all players who watch more than 2 minutes the video:

Show me the code!
import axios from 'axios';

const axiosInstance = axios.create(...);

/**
 * Dynamically process trigger actions based on events received by player
 * for playerID: 00000000-0000-0000-0000-000000000002
 * API Spec: @url: https://docs.gamanzaengage.com/docs-api/platform-rx-api/crm/trigger-campaign/trigger-controller-process-trigger-action
 */
await this.axiosInstance.post(
'https://customer-domain.gamanzaengage.com/rx-api/campaign/v1/trigger/send',
{
    "playerId": "00000000-0000-0000-0000-000000000002",
	"eventName": "video-view",
	"version": "1",
	"eventDate": "2024-04-26T20:59:32.000Z",
	"payload": [
		{
			"key": "url",
			"type": "string",
			"value": "https://www.youtube.com/watch?v=ElFDW8iElVY"
		},
		{
			"key": "score",
			"type": "number",
			"value": "9"
		},
		{
			"key": "feeling",
			"type": "enum",
			"value": "2",
			"options": [
				{
					"key": "action",
					"value": "2"
				}
			]
		},
        {
            "key": "viewDurationInSeconds",
            "type": "number",
            "value": "247,8"
        }
	],
	"keepCounter": true
});

As you can see in the video, PEP continues analyzing the event and checks for changes and updates the event accordingly. You only need to make sure to use the same event name after applying new changes.

Send communication to external person/individual​

Trigger events allow you to send transactional campaigns to individuals who are not registered players. Let's say for example, that you have in your casino a Refer A Friend PopUp, and you want to send an email with a refer code contained in a link to redirect the individual to your casino to become a new Player:

Show me the code!
import axios from 'axios';

const axiosInstance = axios.create(...);

/**
 * Dynamically process trigger actions based on events received by player
 * for playerID: 00000000-0000-0000-0000-000000000001
 * API Spec: @url: https://docs.gamanzaengage.com/docs-api/platform-rx-api/crm/trigger-campaign/trigger-controller-process-trigger-action
 */
await this.axiosInstance.post(
'https://customer-domain.gamanzaengage.com/rx-api/campaign/v1/trigger/send',
{
"playerId": "00000000-0000-0000-0000-000000000001",
	"eventName": "refer-friend-request",
	"eventDate": "2024-03-26T20:59:32.000Z",
	"payload": [
		{
			"key": "referUrl",
			"type": "string",
			"value": "https://www.my-casino.com/referal?code=foo-bar-123"
		},
		{
			"key": "friendFirstName",
			"type": "string",
			"value": "Jane"
		},
		{
			"key": "friendLastName",
			"type": "string",
			"value": "Doe"
		}
	],
	"external": {
		"isExternal": true,
		"contactValue": "[email protected]",
		"channel": "email",
		"language": "EN"
	},
	"keepCounter": true
});

Now notice that the external settings are defined, the important components here are:

  • isExternal: tells the CRM to force send a campaign to an external individual
  • contactValue: the email for the individual who you want to target with the campaign
  • channel: the channel that you want to use to send the communication
  • language: the language used to create the message body

Let's see the full flow from creating the Template, creating the Campaign, sending the event to and finally, seeing the email arrive to the individual.

note

  • By default, the isExternal property cancels the event that allows to send the communication to a player. If you want to send an email to a player, you are obligated to send the event twice, but the second time with the isExternal property with the value false. Take into consideration to set the keepCounter to true only for one of the two events in case you need to track the total of invitations accurately.

  • Because of the nature of trigger events, the playerID is always required, remember that your players are those who trigger a specific event.

Takeaways​

Takeaways🤗
  1. The more context you define for the data in the events, the better the experience will be for the Admin operators.
  2. Be careful with use of the external property. Remember that this feature enables sending communications to individuals that are outside of your platform.
  3. Data types are your friends, use them and define them properly to help your Admin Operators understand the data contained in the events.
  4. Be careful with the naming of your events, be consistent and avoid changes that may break your campaigns. If you need to make breaking changes, make sure to inform your Admin Operators to make the changes in the CRM Campaigns or Gamification contribution rules.

Gamanza Player Engagement Platform offers operators and integrators a powerful toolset through its Trigger Events feature. By leveraging these events, operators gain the ability to finely tune CRM strategies and gamification experiences, ultimately enhancing player engagement.

With the flexibility to dispatch triggers based on specific player activities, Admin Operators can customize campaigns with precision. The structure of Trigger Events, coupled with payload properties and options, empowers operators to extract valuable insights and execute targeted actions seamlessly.

Moreover, the platform's capacity to handle both internal and external events, expands the scope of engagement strategies, allowing for personalized communications beyond registered players. However, it's crucial to exercise caution, especially when utilizing the external feature, to ensure effective communication without compromising data integrity.

By adhering to best practices such as maintaining consistency in event naming, defining data types accurately, and providing ample context, operators can optimize the platform's capabilities and deliver exceptional experiences for players. In essence, with PEP Trigger Events, the possibilities for driving player engagement are endless, limited only by the imagination and strategic perspicacity of the operators.

Happy integration!

Footer diceFooter dice