Metadata implementation

This feature lets you implement event metadata that comes into the event stream and generate even more complex competitions and achievements.

  1. Event metadata from POST /api/:space/events
  2. Custom field creation
  3. Rules creation

1. Event metadata from POST /api/:space/events

First you need an understanding of what kind of metadata you are streaming into the event stream. Here is an example of a post body of an event with metadata included:

[{
	"sourceValue": 1, 
	"memberRefId": "tester", 
	"entityRefId": "fruits", 
	"action": "bet", 
	"transactionTimestamp": "2020-03-05T15:15:44.086+0000",
	"metadata":{
        	"currency": "eur",
        	"amount": 100,
        	"device": "computer"
        }
	
}]

In the example you can see that three different metadata’s of key value pairs are sent to our event stream. These metadata’s will be used in the rules creation of competition or achievement.

2. Custom field creation

In the CompetitionLabs app navigate to Settings → Custom fields.

By pressing Add Custom Field you will need to create custom fields that represent your metadata that comes into the event stream. The custom field creation example is shown.

Name String
Mandatory
The label of the new custom field.

Custom Field Key String
Mandatory
The custom field key is the original representation of the field, with the name as a label that can be added as a descriptor.

Description String
Optional
The description of the custom field for the client’s use.

Field type Enum
Mandatory
The type of text that you need for the field (word, number etc.).
  • Text
  • Number
  • Text-Array
  • Number-Array

Applies to Enum
Mandatory
The section of the CompetitionLabs platform to which this custom field applies.

In our case three different custom fields have to be created. An example below is shown how the custom fields will look after creation.

Note that you only need to create custom fields that will be used in the rules creation.

You can read more about Custom fields creation here.

3. Rules creation

Custom fields will be used in the rules creation:

ACHIEVEMENT RULES

Achievement Rules section can be found by navigating to Achievement creation → Step 6: Achievement Rules.

You can navigate to the Achievement rules creation here. The full tutorial of an Achievement creation can be found here.

CONTEST RULES

Competition Rules section can be found by navigating to New competition – Quick → Step 4: Simple Competition Rules

The full tutorial of a Competition creation can be found here.

An example is shown of the rules in the competition creation section. The custom fields that were pre created in our previous step is populated here in the rules Fact. Here you can see that the points will be calculated if any of the metadata is selected as the Fact of the rule.

EXAMPLE ​If “The currency” is selected as the Fact, the opertaor is selected as “is” and the constant is inserted as the “eur” then every event’s source value will be counted in the leaderboard that has this metadata“currency”: “eur in their event body.

You can read more about Rules in our rules guide here

Here is a basic example of an action “Bet” and metadata combined together.

If a Player is sending event data and the action that is being sent is “bet”, the metadata key and value pair is “currency”: “eur” and “device”: “computer” that means that the points will be calculated only then. If any of these 3 fields are excluded – then the points will not be calculated.

EXAMPLE ​A correct example of a post body that will calculate points in the competition leaderboard:

[{
	"sourceValue": 10, 
	"memberRefId": "tester", 
	"entityRefId": "fruits", 
	"action": "bet", 
	"transactionTimestamp": "2020-03-05T15:15:44.086+0000",
	"metadata":{
        	"currency": "eur",
        	"amount": 100,
        	"device": "computer"
        }
	
}]

In this example the member “tester” will have 10 points (that is only if the products adjustment factor is set to 1) because the sourceValue that was sent is 10 and all the rules facts were present in the post body.

EXAMPLE ​An example of a post body that will NOT calculate points in the competition leaderboard:

[{
	"sourceValue": 10, 
	"memberRefId": "tester", 
	"entityRefId": "fruits", 
	"action": "bet", 
	"transactionTimestamp": "2020-03-05T15:15:44.086+0000",
	"metadata":{
        	"currency": "dol",
        	"amount": 100,
        	"device": "computer"
        }
	
}]

In this example the member “tester” will not receive points in the leaderboard because the rules “The Currency is eur” is incorrect. This member sent a post body of “dol” in the metadata “currency”.

Note! The metadata key value pair has to be exact of what is sent in the event stream.

  1. If the created custom field key value pair of a string to text is not equals to the metadata key and value that is sent then the points will not be calculated for the competitions.

  2. If the created custom field key value pair of a string to number is not equals to the metadata key that is sent then the points will not be calculated for the competitions. The value in this case depends on the rules – if the value needs to be higher than 100 then the points will only be calculated when the value of the metadata is sent 101 and more. Here is an example of the rules – fact is “amount” the operator is “more than” and the constant is 100

If you have any more questions about event metadata and custom fields please contact us.

Back To Top