Getting Started with the xAPI iOS SDK, Part 2 of 2

Experience API, Mobile Development Comments (0)

If you missed my previous post, please be sure to take a look at part 1 of 2.

4. Creating Statements

In its most basic form, the Experience API (xAPI) statement is in the form of “I did this.” So, to create a statement, we need to define the “I” (the actor), the verb, and what the actor did (the “this”). In our first view controller, we’re going to define all three of these items, create the statement, and then send the statement to the LRS.

Before we begin, let’s make sure we import the xAPIKit headers by adding #import <xAPIKit/xAPIKit.h> to the top of the implementation file (ViewController.m).

Now, let’s first create the actor of our statement. The actor is simply going to be specified by whatever email address is entered into the email address field. Inside the -bookmarkAction: method (which gets called when the user taps the button), let’s create an agent with the email address of whatever is in the field.

EXPAgent *actor = [EXPAgent agentWithName:nil andMbox:self.emailAddressField.text];

Next, let’s create the verb for the action, “shared.” A verb is composed of a URI (that uniquely identifies the verb) and a human-readable portion. Let’s reference the list of community verbs so we don’t create a unique verb if there is already one defined. Looking at the list, we see that “shared” is already defined by ADL so we’ll use that.

EXPStatementVerb *verb = [EXPStatementVerb verbWithURI:@"http://adlnet.gov/expapi/verbs/shared" andDisplayString:@"shared"];

Finally, let’s create the activity, the ID of which will just be the URL that was entered.

EXPActivity *activity = [EXPActivity activityWithId:self.urlField.text];

Let’s put it all together into a statement and send it to the LRS.

EXPStatement *statement = [EXPStatement statementWithActor:actor statementVerb:verb andObject:activity];
[[EXPAPI defaultAPI] putStatement:statement delegate:self];

Again, by specifying the delegate as self (the view controller) we’re telling the SDK to let the view controller know when the statements have been sent to the LRS. Just as before, we need to implement a few of the methods in the protocolEXPAPIStatementRequestDelegate. This time, we’ll implement the -statementsStored:and methods-statementsFailedToPersist:withError:. In both cases, we’ll display an alert. If it was successful, the alert will simply say “Statement stored!” If something went wrong, we’ll display the error message.

- (void) statementsStored:(NSArray *)statements
{
[[[UIAlertView alloc] initWithTitle:@"Statement stored!" message:nil delegate:self cancelButtonTitle:@"OK" otherButtonTitles: nil] show];
}
- (void) statementsFailedToPersist:(NSArray *)statements withError:(NSError *)error
{
[[[UIAlertView alloc] initWithTitle:error.localizedDescription message:nil delegate:self cancelButtonTitle:@"OK" otherButtonTitles: nil] show];
}

And that’s it! Try out the application. Enter a URL and an email address and click bookmark. Then head over to the second tab and see your statement!

If you’re having some trouble getting it to work, you can download the completed project.

The Statement Queue

Another feature of the xAPI iOS SDK is the statement queue. Although users on a mobile device will frequently have an Internet connection (whether it be over their cellular network or over Wi-Fi), there will still be points where the device will be unable to communicate with the LRS. Perhaps the user has no reception, is having trouble with their Internet at home, or simply enabled Airplane Mode. Instead of rendering the app entirely unusable, we could continue to report statements, but just store them locally and wait for an Internet connection to become available and then send them all at once to the LRS.

The iOS SDK has a feature called the statement queue. Instead of immediately trying to send statements to the server, it will place them inside of the queue to ensure that they can be persisted to the LRS.

To utilize the statement queue in our application, we just need to replace this line from above:

[[EXPAPI defaultAPI] putStatement:statement delegate:self];

with this line:

[[EXPAPI defaultAPI] storeStatement:statement];

This will add the statement to the queue and will be sent to the LRS when possible. By default, it tries every 2 minutes. You can change this interval by modifying the statementPostInterval property on your default EXPAPI:

[[EXPAPI defaultAPI] setStatementPostInterval: 30]; // Attempts to clear the queue every 30 seconds

The statement queue will hang onto your statements until they can be sent to the LRS. It doesn’t matter if the battery suddenly dies or the user quits the app – the next time the app is launched, the statements will be in the queue and ready to go to the LRS.

You may have noticed that the method storeStatement: does not allow you to set a delegate. The reason is simple: when you add a statement to the queue, it may be sent to the LRS immediately (if there’s a connection) or in an hour (if the user had no Internet connection when the statement was created). It’s possible (in fact, likely) that when it does get sent to the LRS, the delegate (a view controller, for example) may not exist anymore.

So, instead of defining a delegate for the statement queue, you can add an observer to the default notification center. If you want your view controller to receive notifications of when the statements have been received by the LRS, add an observer for the EXPStatementsPersistedNotification notification. You can also add an observer for the EXPStatementsFailedPersistingNotification notification. Just don’t forget to remove the observers when you’re done with them!

Conclusion

This is just the tip of the iceberg in terms of what you can do. The xAPI is very powerful with thousands of possibilities when it comes to reporting events in your application. The xAPI iOS SDK attempts to take all these capabilities and put them in the hand of the iOS developer with a simple, yet verbose, SDK.

Be sure to check out the xAPI Statement Viewer on the iOS App Store to see another small example of what the xAPI iOS SDK can do. Better yet, go download the demo version of the SDK and try it out for yourself.







If you liked this tutorial or want more examples, let us know in the comments. If you’re using the SDK, let us know what kind of statements you’re creating with the iOS SDK and how we can make the SDK better.

Follow Float
The following two tabs change content below.

» Experience API, Mobile Development » Getting Started with the xAPI...
On December 6, 2012
By
,

Leave a Reply

Your email address will not be published. Required fields are marked *

« »