SendSessionEvent() Function

Overview

The SendSessionEvent() function is how you send any data to the PIXO Platform during a session. It:

Constructs an xAPI statement from provided session data
Sends an event with xAPI statement data
Returns FALSE if:
- there is no logged in user
- if JoinSession() has not been called to start a session
- if the InStatement.Actor has had any data filled
- if any of the following members in InStatement have not been set:
  - InStatement.Verb
  - InStatement.Verb.ID
  - InStatement.Target

Handling Response

OnRequestComplete and OnStaticRequestComplete with the type EApexRequestType::SessionEvent is called when the user was able to join the session successfully
OnRequestFail and OnStaticRequestFail with the type EApexRequestType::SessionEvent is called when the user was not able to join the session or when the server is not able to be reached

Blueprint Example

Parameters

The SendSessionEvent() function has one required parameter:

InStatement:FXAPIStatement — the object that provides all the necessary data to generate the xAPI statement

xAPI in Unreal

The Apex SDK, as well as the PIXO Platform, expect data to be sent in the xAPI format specification for information consistency. The Apex SDK documentation should provide enough context for you to effectively use our implementation of the package, but if you want to dig deeper, the full documentation on the standard is available here.

Relevant Members

Set Manually

The following properties are available for you to set yourself. Verb and target (i.e. object) are required to create a valid xAPI statement, while result and context are available should you wish to use them.

Required

Verb — the action the user took
Target — the object of the action

Optional

Result — data relating to the result of the action taken
Context — data that helps describe the conditions surrounding the action, both in game and at a system level:
- Context.Registration, Context.Platform, and Context.Revision are set automatically
- Context.Revision is set to equal the "ModuleVersion"

Set Automatically

You will see the following properties show up on the PIXO Platform report, but you should not set them yourself — they are always the same, and will be set for you by the SDK:

Actor — set to the logged in user.
Timestamp — records the time the event happened. Uses the headset system clock, and is set to UTC.
Version — the version of the xAPI spec being used. Currently 1.03.

Example Code

There are a lot of possible ways to build an xAPI statement, with a LOT of potential information you could include. This flexibility is valuable if you have complex data you need to track. But sometimes, maybe even most of the time, all you need is something simple.

All an xAPI statement truly requires is an Actor, a Verb and an Object (which the Apex SDK refers to as a "Target"). The SendSessionEvent() function will add the Actor information (i.e. the logged in user) to the passed InStatement, so all you need to provide is a verb and an object, and their associated IDs.

The following code demonstrates how to do this:

FXAPIStatement EventStatement;
EventStatement.Verb.ID = TEXT("https://pixovr.com/xapi/verbs/exampleVerb");
 
// The Target is equivalent to the object in the xAPI specificiation
EventStatement.Target.ID = TEXT("https://pixovr.com/xapi/exampleProject/objects/exampleObject");
 
UApexAPI* ApexAPI = GetGameInstance()->GetSubsystem<UApexAPI>();
ApexAPI->SendSessionEvent(EventStatement);

There are a few things to note:

The Unreal Apex SDK calls objects "Targets". This is a convention to prevent conflicts with the object keyword. Any data you add to the EventStatement.Target property will show up as an object property in the PixoVR Platform.
Objects (targets) can be one of several types, but Activity is by far the most common type. Refer to the official xAPI spec for more information about the other types.
The Verb.ID and EventActivity.ID need to be an IRI formatted FString.

Now, if the simple version is not enough for your use case, we've provided a more detailed example below that includes the data that we feel is most relevant to the Apex System and should cover most of your needs.

You are of course welcome to include any additional properties you would like in your report, and if you have any questions about how to do so or about best practices feel free to contact us.

FXAPIStatement EventStatement;
 
// Verb
EventStatement.Verb.ID = TEXT("https://pixovr.com/xapi/verbs/reported");
EventStatement.Verb.Display.Add("en","Reported");
EventStatement.Verb.Display.Add("es","Reportado");
 
// Object
// Note: Activity is one of four ObjectTypes, but the one that 99% of statements on
// Apex should use.
EventStatement.Target.ID = "https://pixovr.com/xapi/currentmodule/exampleObject";
 
//Result
EventStatement.Result.Completion = true; //did they complete the event
EventStatement.Result.Success = true; //did they get a passing score or otherwise succeed at the event
EventStatement.Result.Duration = TimeSpan.FromSeconds(15);//how long did they spend on the event
EventStatement.Result.Response = "answer"; //how they answered a question, or otherwise responded
EventStatement.Result.Score.Max = 100;
EventStatement.Result.Score.Min = 0;
EventStatement.Result.Score.Raw = 80;
EventStatement.Result.Score.Scaled = 0.8;
 
//Context
EventStatement.Context.Extension.AddCustomString("https://www.pixovr.com/xapi/extensions/iri_extension","value");
EventStatement.Context.Extension.AddString("simple_key", "value");
 
UApexAPI* ApexAPI = GetGameInstance()->GetSubsystem<UApexAPI>();
ApexAPI->SendSessionEvent(eventStatement);

Next Article: Extensions

Previous Article: CompleteSession() Function