Events

Describes what customer events are in the context of Uplyft and your loyalty program, how to structure them and how to pass events to Uplyft using the createEvent mutation of the Uplyft Graph API.

If you want to skip the documentation and get a hands-on experience, download the GraphiQL Explorer, add the endpoint (https://api.uplyft.com​) and authorize with app ID and test app secret.

Step 1: Prepare your Events

Now that you have access to the Uplyft Graph API, it is time to prepare your events.

You can pass events with and without transactions which is important to later compare the effects and uplift of your loyalty programs.

To pass events to Uplyft you use the createEvent mutation:

createEvent(
businessValue: FiatValue!
action: Action!
objects: [Object]!
tags: [String]
labels: [EventLabel]
transaction: EventTransaction
uniqueId: String
): Boolean

Creating an event consist of a mandatory first part, that sends information about the action which your customers perform on certain object/s and how much businessValue your company generated through these events.

The second optional part enables you to attach a uniqueId (e.g. receiptId), to add meta-data such as tags or labels and last but not least to book a transaction, e.g. rewarding a user with miles or points. We will explain the different options below.

The uniqueId is used as a duplicate check, so it always needs to be unique for every event. For example you could pass your internal receipt ID to make sure, that one transaction in your system is never process twice. Even if you happen to send the event twice. It is optional, and we will generate a uniqueId if left blank.

Step 2: Business Value

The main objective of any loyalty program or activity is to generate an uplift on your customer retention or sales. Therefore it is essential that you define the business value each customer event generates for your business. This is obviously easy when thinking about sales, as the generated revenue is the business value, however other customer actions such as the registration, a store or event visit, or referral also generates important business value for your company.

Business value is calculated in fiat currency as follows:

businessValue: {
amount: 1,
currency: eur
},

We recommend to align the business value that you pass to Uplyft with your controlling or financial department or even management. It is essential that you pass a business value that represents the real value generated because Uplyft Analytics is mainly build around showing you your generated business value with certain customers, segments or campaigns.

It is important that you can trust your Uplyft business value. Therefore think about which numbers you pass to Uplyft, they will be the baseline for the calculation of your customer value and uplift.

Step 3: Choosing actions and objects

The most important part about running a loyalty program is to structure your data correctly. Otherwise you will never be able to actually gain value from rewarding and thereby tracking your customer behavior.

Uplyft has developed a new way of looking at customer events in the context of loyalty programs and the customer lifetime value. We have used Facebook's Actions/Objects as inspiration. The idea is to structure complex customer relationships and behavior in a simple comprehensive approach.

To do so, you simply select an action from the following list that best describes the customer action that caused the event you are passing to Uplyft:

Action

Comment

purchase

a customer purchasing a product

watch

watch a movie

checkin

check in to a location

connect

connect to an app

share

share content

follow

follow an account

listen

listen to music

install

install an app

predict

predict a match result

invite

invite a friend

signup

sign up for a product or service

login

log in to an account

run

run a distance

bike

bike a distance

walk

walk a distance

place

place a bet

visit

visit a match

read

read a book

subscribe

subscribe to a newsletter

add_to_cart

add a product to a cart

submit

submit a survey

retour

retour a product

deposit

make a deposit

book

book a flight

rent

rent a car

custom

custom

Next, you simply add all objects that this action was performed on. Event objects have a type, an id and a name which enables advanced analytics and machine learning in a later step.

objects:[
{ id: "4587858", type:product, name:"Nike Shoe X - Men - Size:10"},
{ id: "4578784", type:product, name:"T-Shirt Christmas - Women - Size:M"}
...
],

Essentially objects define what your customers purchased, or which exact event customer visited. First you select the type from the predefined list to best describe the nature of the object.

Object

Example

video

watch a video

location

check in to a location

content

share content

account

follow an account

music

listen to music

app

install an app

item

purchase an item

shop

visit a shop

match

visit a match

membership

sign up for a membership

money

deposit money

user

invite a user

product

purchase a product

service

subscribe to a service

fitness

do fitness

website

visit a website

book

read a book

survey

submit a survey

level

complete a level

tv

watch tv

page

visit a page

audio

listen to audio

event

visit an event

distance

cover a distance

voucher

redeem a voucher

task

complete a task

ticket

purchase a ticket

campaign

share a campaign

quiz

submit a quiz

newsletter

subscribe to a newsletter

ride

purchase a ride

vehicle

rent a vehicle

room

book a room

custom

custom

The id should describe the object in question, therefore this field should not be a unique identifier for each event, but for each object. The best example are EAN codes in the context of eCommerce. In the case of events such as a soccer game, it should be a unique id for this match, or a certain concert.

Last but not least, the name should simply describe the id semantically so your marketing managers can later read the analytics better. Meaning, id and name should be consistent with each other.

Make sure to put all objects that were purchased in a single customer event in just one event. E.g. if a customer purchased a basket of products in 1 transaction on your side, also just pass 1 event with multiple objects.

Step 4: Using Tags and Labels

Until now, Uplyft has given you a very much predefined structure to pass your event data, however you might want to add custom meta-data to your events to later search, filter or analyze your customer events. In order to enable this flexibility, we have developed tags and labels.

Remember, tags, labels and transactions are optional, however they are highly important to use your Uplyft Analytics to increase retention and business value. Contact us if you need support or have ideas of how to better show the uplift your loyalty implementation creates for your.

Tags

Tags are simple strings that you can attach to an event. There are meant to give you a simple way to literally "tag" your events. Example use-cases are to add the versions of your implementation, or which channel the customer performed the event on. Tags are a great way to pass meta-data without knowing specifically what you will need it for later, however they are not intended for specific use-cases like user ids, or category ids. For that, we have developed labels.

Labels

Labels enable you to pass along key:value meta-data to add custom structure to your customer events. They are essential to understand and uplift your customer loyalty and lifetime value. You best know which meta-data is most important for your specific business-model, however our data engineers are more than happy to assist you in structuring your data. Simply ask your account manager or contact us via support@uplyft.com.

labels: [
{key: "uuid", value:"8764897765493"},
{key: "transactionId", value:"456789"}
]

Here are some examples of key:value use-cases:

Key

Value

uuid

8764897765493

segmentId

456446-M

campaignId

BlackFridaySale

transactionId

456789

Step 5: Event Transactions

As mentioned above, you can pass events with and without transactions. A typical use-case is, that some of your customers participate in your loyalty program and some customers don't. In this case, you pass all events to Uplyft and add transactions to the ones, where you have a walletAddress for the specific loyalty program.

In the following example, we pass a typical event of a user purchasing a T-Shirt and a ticket to a concert at the same time. In this example, the customer uses a Miles & More Service-Number to collect Miles & More award miles. The customer purchased these two products for a total price of 100 Euros and received 100 Miles & More Award Miles.

mutation {
createEvent(
businessValue: {
amount: 100,
currency: eur
},
action: purchase,
objects:[
{
type:product,
name:"T-Shirt Christmas 2018 - XXL - Men",
id: "EAN-4585485"
},
{
type:event,
name:"LadyGaga18/19 Tour - Olympiastadium Berlin",
id: "2939938484"
}
],
tags:["integration.v.1","Linux","RandomTag"],
labels:[
{ key: "uuid", value: "24585485485" },
{ key: "campaignId", value: "X484852525" }
],
transaction: {
walletAddress: "9922XXXXXXXXXX",
baselineAmount: 100,
currency: milesandmore,
userFacingMessage: "Thank you"
},
uniqueId: 123456789
)
}

You can define customer conversions between businessValue and baselineAmount. Depending on the loyalty program and price for which you purchase miles or points, you might want to reward your customer with e.g. 10 Fanmiles per Euro business value or 1 Miles and More award mile per 1 Euro business value. To reward intended behavior, you can also choose to reward double miles for second purchases, etc. Simply pass the desired combinations through the createEvent mutation.

If you navigate back to your Uplyft Business-Account you can check the passed events and their status which in our example above will show the following result.

Since we passed an invalid Wallet address, the event fails. You can check the error code with a simple mouseover on the error icon.

To pass events without a transaction, simply remove the transaction part and pass the event to the same createEvent mutation as above. The following examples shows the same event without a transaction rewarding the user with Miles & More.

mutation {
createEvent(
businessValue: {
amount: 1,
currency: eur
},
action: purchase,
objects:[
{ id: "EAN-4585485", type:product, name:"T-Shirt Christmas 2018 - XXL - Men"},
{ id: "2939938484", type:event, name:"LadyGaga18/19 Tour - Olympiastadium Berlin"}
],
tags:["integration.v.1","Linux","RandomTag"],
labels: [
{ key: "uuid", value: "24585485485" },
{ key: "campaignId", value: "X484852525" }
],
uniqueId: 123456789
)
}

You can check all events without a transaction on your Business Account in the program navigation bar.

As long as the structure of your API call is correct and the passed data is plausible, the Uplyft Graph API always returns "createEvent": true. If e.g. the Wallet Address is wrong, or your business account has no permissions to book Miles & More Award Miles which causes the transaction to fail, you can check the errors in the event stream in your Uplyft account. Therefore, please remember and note that a successful creation of an event in Uplyft does not mean the intended transaction also succeeded. We are working on an endpoint through which you can check the status of a transaction. If you are interested in using it, please contact your account manager or support@uplyft.com.

Step 6: Further considerations

You can structure and test your events against the Uplyft development environment and check the results through your Uplyft development business account.

Please find some example calls we have prepared in the table below. You can copy and past the mutation templates to build your own.

Without Transaction
Miles & More Transaction
Fanmiles Transaction
mutation {
createEvent(
businessValue: {
amount: 1500,
currency: eur
},
action: purchase,
objects:[
{ id: "EAN-ID", type:product, name:"T-Shirt Christmas - Size: M - XYZ"},
{ id: "insuranceId", type:insurance, name:"Health Insurance"},
{ id: "matchId", type:ticket, name:"Homegame Team AvsB - 18/19 - Away"}
],
tags:["v.1","web","RandomTag"],
labels: [
{ key: "uuId", value: "24585485485" },
{ key: "collectionId", value: "X484852525" },
{ key: "paymentId", value: "X484852525" },
{ key: "campaignId", value: "X484852525" }
],
uniqueId: 123456789
)
}

mutation {
createEvent(
businessValue: {
amount: 1500,
currency: eur
},
action: purchase,
objects:[
{ id: "EAN-ID", type:product, name:"T-Shirt Christmas - Size: M - XYZ"},
{ id: "insuranceId", type:insurance, name:"Health Insurance"}
{ id: "matchId", type:ticket, name:"Homegame Team AvsB - 18/19 - Away"}
],
tags:["v.1","web","RandomTag"],
labels: [
{ key: "uuId", value: "24585485485" }
{ key: "collectionId", value: "X484852525" }
{ key: "paymentId", value: "X484852525" }
{ key: "campaignId", value: "X484852525" }
],
transaction: {
walletAddress:"9922XXXXXXXXXXX",
baselineAmount: 1500,
currency: "milesandmore",
userFacingMessage:"Your Company Name"
},
uniqueId: 123456789
)
}

mutation {
createEvent(
businessValue: {
amount: 1500,
currency: eur
},
action: purchase,
objects:[
{ id: "EAN-ID", type:product, name:"T-Shirt Christmas - Size: M - XYZ"},
{ id: "insuranceId", type:insurance, name:"Health Insurance"}
{ id: "matchId", type:ticket, name:"Homegame Team AvsB - 18/19 - Away"}
],
tags:["v.1","web","RandomTag"],
labels: [
{ key: "uuId", value: "24585485485" }
{ key: "collectionId", value: "X484852525" }
{ key: "paymentId", value: "X484852525" }
{ key: "campaignId", value: "X484852525" }
],
transaction: {
walletAddress:"3104XXXXXXXXXXXX",
baselineAmount: 15000,
currency: "fanmiles",
userFacingMessage:"Your Company Name"
},
uniqueId: 123456789
)
}

Download the GraphiQL GUI from Electron to prepare and test Graph Queries and mutations. Download https://electronjs.org/apps/graphiql

If you have feedback or any other questions, please contact your account manager or support@uplyft.com. It is our goal to help you manage your customer data that directly generates additional business value and uplift on retention and revenue.

This is what Uplyft is all about.