ximpel_website_top home features showcase downloads documents faq contact
Evaluating scores
Description: This tutorial describes how you can (programmatically) evaluate scores and subsequentially link actions to certain scores.
Overview

Within XIMPEL, scores are used to keep track of how the user performs. Besides using scores to diagnose how the user has done after the XimpelPlayer has ended, it is also possible to affect what the user sees when XimpelPlayer is running.

In the first part of this tutorial we will look at how to evaluate the score after XimpelPlayer has ended. In the second part we will look at how to evaluate scores at runtime by using callbacks. Finally, we explain how to keep track of multiple score parameters.

Throughout this tutorial we will be using the XIMPEL advanced package to create custom ximpelApps.

You can define rules for evaluating the score after XimpelPlayer has ended by adding rules to the config file:

...
  <scoreMessages>
    <scoreThreshold upperlimit="1" message="That's really bad..."/>
    <scoreThreshold underlimit="3" message="Well done!"/>
    <scoreThreshold underlimit="1" upperlimit="2" message="Thanks for playing! Try again."/>
  </scoreMessages>
...

A rule is defined in a scoreThreshold tag and can contain an upperlimit, underlimit and message attribute. Rules are executed in the order they are defined. This means that if there are conflicting rules, the first defined rule is used.

You can place callbacks in a subject tag by adding the event attribute with an optional eventparam attribute. The event attribute should contain the name of an event that you will be listening to in the ximpelApp. It is highly recommended to use an event name which is not already used within Flex or XIMPEL. The eventparam attribute can be used to pass along additional information, which is accessible when the callback event has been passed through. A playlist with callbacks could look as follows:

<ximpel>
  <subject id="IntroVideo">
    <description>Introduction video</description>
    <score value="0"/>
    <media>
      <video file="fast1.flv" leadsto="SecondVideo">
        <canvas>
          <overlay x="0" y="0" width="400" height="300" leadsto="ThirdVideo"
           description="Click me!"/>
        </canvas>
      </video>
    </media>
  </subject>

  <subject id="SecondVideo" event="scoreEval">
    <description>Again fast</description>
    <score value="5"/>
    <media>
      <video file="fast1.flv"/>
    </media>
  </subject>

  <subject id="ThirdVideo" event="scoreEval">
    <description>Again fast</description>
    <score value="-10"/>
    <media>
      <video file="fast1.flv"/>
    </media>
  </subject>

  <subject id="GoodEnd">
    <description>Good ending</description>
    <score value="0"/>
    <media>
      <video file="goodEnding.mp4"/>
    </media>
  </subject>

  <subject id="BadEnd">
    <description>Bad ending</description>
    <score value="0"/>
    <media>
      <video file="badEnding.mp4"/>
    </media>
  </subject>
</ximpel>

This playlist contains two callbacks. Furthermore, there are two subjects that are not linked in the playlist. These subjects will be used when evaluating the scores. When you click on the overlay, you will get the bad ending. If you do nothing, you will get the good ending.

When evaluating the score at runtime, the first step is to handle the callbacks by making sure that XimpelPlayer is listening to the callback event. In ximpelApp we add an event listener in the function init():

...
    myXimpelPlayer.addEventListener("scoreEval", handleScoreCallback);
...

Next, we create a new function handleScoreCallback():

private function handleScoreCallback(event:CallBackEvent):void {
    myXimpelPlayer.addEventListener(XimpelEvent.COMPLETE, evaluateScore);
}

In the function handleScoreCallback() we add a new event listener that listens for XimpelPlayer to reach the end of the playlist. When that happens, the score is finally evaluated in the function evaluateScore():

private function evaluateScore(event:XimpelEvent):void {
    myXimpelPlayer.removeEventListener(XimpelEvent.COMPLETE, evaluateScore);
    ximpelAppViewStack.selectedChild = ximpelScreen;
    var myScore:Number = Number(myXimpelPlayer.getTotalScore())/myXimpelPlayer.scoreMultiplier;
    if (myScore > 0) {
        myXimpelPlayer.goToSubjectByIdAndPlay("GoodEnd");
    }else {
        myXimpelPlayer.goToSubjectByIdAndPlay("BadEnd");
    }
}

After the score has been evaluated, you immediately jump to the subject with the id you passed along as parameter ("GoodEnd" or "BadEnd" in above example).

When you have multiple score parameters you keep track of, you first need to add the type attribute to the playlist for each score instance in a subject:

...
  <subject id="decision3">
    <description>You made a decision</description>
    <score value="2" type="people"/>
    <score value="-1" type="planet"/>
    <score value="1" type="profit"/>
    <media>
      <video file="dancing.mp4"</video>
    </media>
  </subject>
...

In above example three score types are used: people, planet and profit. The score values are added to the current total as soon this subject is started. Furthermore, you can also define negative scores if you want to reduce a certain score. Lastly, each score type is independent from one another. You can leave one out or add more depending on the score parameters you want to update with a certain subject.

Each score parameter can be referenced in your code by using the XimpelPlayer function getScoreByName():

...
    var peopleScore:Number = Number(myXimpelPlayer.getScoreByName("people"));
    var planetScore:Number = Number(myXimpelPlayer.getScoreByName("planet"));
    var profitScore:Number = Number(myXimpelPlayer.getScoreByName("profit"));

    if (peopleScore > 1 && planetScore > 5 && profitScore < -1) {
	    ...
    }else if (...){
	    ...
    }...
...

By using multiple score parameters you have more possibilities in profiling the user. Furthermore, this information can be used to create a more customized user experience, because you have more details about choices that were made.