Contagion Media has created a server system to host and interconnect digital assets. The Contagion Universe is the totality of all the digital assets.
Digital Galaxy
Within this Universe a publisher can set up a Digital Galaxy. This is an isolated zone where a publisher can publish an array of different assets, and interconnect them in one cohesive interface. An example might be a film producer setting up a Digital Galaxy which contains and promotes all assets associated with its movies.
Digital Worlds
Within the Digital Galaxies are Digital Worlds. The Digital World is term created to cope with a shift in the thinking about interactive assets similar to that in the shift to Web 2.0. Taking a game as an example, traditionally a game is a one way enterprise. The publisher produces a game and the consumers play it. Contagion shifts that model with digital worlds. Each digital world can contain content contributed from multiple sources, from users to publishers, and that content will be played in a variety of social contexts. The digital world is a single interactive system that ties this together.
Content Package
A Content package in a digital world is the personalised content that a user has published into that world; for instance in a maze game a user may publish a new maze design, or in a mah-jong game a new card layout. Content packages allow the user to release their own content for themselves or others to users.
Context
A context is the social structure of those interacting through a particular digital asset. For instance a user might create a new maze layout for a Pac-Man-like game and then challenge his friends in a competitive league to see who can get the best score. The maze would represent a content block, whereas the league of friends is the context.
Digital Interaction
A digital interaction is the fundamental touch point in the Contagion System. It represents a user interacting at a particular time with a particular asset. Each digital interaction is defined by the User’s identity, the content they are interacting with and the context in which they interact with it.
User Profile API
In order for a game to operate socially it needs access to social data about the user. This access is given through the User Profile API. This API provides three types of information
|
User Information
|
In API 1.0, Contagion provides access to the user’s first and last name as well as a photo
|
|
Friend Information
|
In addition to information about the user, contagion gives access to the first name, last name and photos of any friends stored in the contagion universe
|
|
Context Friends
|
Context friends are a subset of the friend’s information. Only those friends’ details that have elected to be part of a context are present in the Context friends array
|
Data Storage API
The data storage API allows games the chance to store data easily. There are three realms in which data can be stored:
· Content
· Context – User Information
· Universal User Information
Content
Any Context has a single content package associated with it. No matter the context, all assets can easily access the Content Data through the Content property of the wrapper API. In some context’s it is also possible to write data to the content, typically when the context in use is the solo context for the author of the content item. Setting the Content property, in a context which allows writing to the content, results in that data being written to the server. The changes will take immediate effect in all contexts and all users that access that content package.
Context – User Information
Within any context it may be necessary to record information about the user, for instance their preferences. In order to record this information all the digital asset needs to do is store or retrieve data from the ContextUserInformation property of the wrapper API. The wrapper takes care of the account management and storage of information so that it will be available the next time the user interacts with that asset in that context.
Every context contains a single content package. In some types of contexts the content item is editable and in others it is not. The currently available context types are:-
|
Value
|
Name
|
Open to
|
Content Editable
|
|
1
|
Solo
|
Author Only
|
Yes
|
|
2
|
Solo Locked
|
Author Only
|
No
|
|
3
|
League
|
Author & Friends
|
No
|
|
4
|
Collaboration
|
Author & Friends
|
Yes
|
|
5
|
Challenge
|
Author & Friends
|
Author – Yes , Friends - No
|
Whether the content is editable depends on whether it makes sense within that context. A competitive context like a league would be undermined if the rules of the game changed half way through, so the content is read only. On the other hand if the context is a collaboration then the content needs to be editable to everyone so they can contribute.
Every context has a single distinct content package, meaning that changes in one context to a content package do not effect another context. In future API’s contagion may change this architecture. Content items can however be copied from one context to another. For instance friends could work together to build a new gaming challenge in a collaboration context. Once finished they may copy this data into a new league context to compete against eachother.
Universal – User Information
Some data may also need to be stored on the user which applies universally to all contexts that this asset operates in. The wrapper API provides the UniversalUserInformation property for this purpose. Again the wrapper takes care of the account and data management so that this data will be available to the asset whenever that user is playing.
Incentive API
In any web-based incentive scheme the prize fund needs to be managed centrally and securely on the server end of the deployment. The incentive API performs this task simply for an online asset.
If an event occurs in the game that requires a prize draw to occur then this is passed to the API. The contagion server calculates the probability of different prize wins depending on the current state and requirement of the fund and then performs a random draw, before passing the result back to the asset and distributing any prize confirmations securely by email.
The API also handles tournament scenarios. When tournaments are in play, score data is encrypted back to the server to ensure that they are genuine. This data is then securely analysed on the server, notifications of prize winners are then made by email and on the context data.
Score & Playback API
In order for players to track their top scores, or to compete socially whether that is with their friends or in a public competition, score data has to be stored on the server. The Score & Playback API provides a simple framework for storage and retrieval of this data. The top 10 high scores for the context can be read from the Scores property of the API, new scores can be posted with the PostScore method.
Contagion also allows the storage of play data. Play data is used to replay part or all of the game that was played. This is a useful tool for increasing game engagement. Users not only get to see what others have scored, but also how they managed to achieve their scores. The top 10 high scoring games play data is available from the PlayData property of the API.
Metrics API
Other than sales, the recording of information about users is the most important function of any digital touch point. Interactive assets like games can harvest vast amounts of information about users. Using the contagion dashboard, a metrics system can be set up to define the information being recorded and how it should be analysed.
The metrics API is a flexible system for allowing formatted data to be captured and returned to the server. Metrics is recorded rather like on tape as a single timeline of recorded events. The recordings are organised into segments which represent some logical unit of interaction with the user, for instance in a game that would represent a single play of the game. The API records three types of metrics:-
· Events: Related measurements which are associated with a single moment in time.
· Time Spans: Related measurements which are associated with a time span.
· Segment Data: Related measurements which are associated with the whole metrics segment.
Events and Time spans are recorded in the same recording stream, where as segment data is recorded in a separate stream. All recording functions in the API are additive, meaning that each call adds new data to the recording rather than overwriting existing data. At the start of each segment the asset needs to call the InitiateMetrics method which tells the Server to start recording on a new metrics segments.
Metrics recordings are stored securely on the server, organised by time, user id and asset id. The store of data can then be accessed and analyzed through the contagion dashboard.
Closing an Asset
There are two ways an asset can be asked to close. One is through the Close function and one is through the Kill function. The close function is a notification that the user has asked the wrapper to perform a task which requires the closing of the asset. The user may be unaware of this and so the Close function does to force the asset to shutdown. The wrapper makes the request known to the asset through the close function. The asset can then check with the user if they really want to quit a game or save data, and if so can confirm the close by calling the ConfirmClose method of the API.
The kill method represents the opposite scenario, the asset is required to close. The asset will be disposed of when the method returns, and so the asset must clean up immediately, saving data etc. And there is no chance to interact with the user.
Contagion Game Wrapper Reference
The Contagion Game Wrapper will enact the following functions for Contagion Hosted Games
Game Data
AvailableContexts
Item Type: Property
Direction: Get
Data Type: String
Value: An XML file describing the available contexts
Description: The Context XML is as follows
<Contexts>
<Context>
<ID>the id of the context</ID>
<Name> the name of the context</Name>
<Type> the type of the context</Type>
<Score>the score ranking system of the context</Score>
</Context>
....
</Contexts>
GameData
ItemType : Property
Direction: Get
Data Type: String
Value: Data stored on the server by the game publisher to allow changes to the behaviour of digital assets in real time.
Description: Game data is not parsed by the Contagion System and so can contain any data the publisher wishes to store
PrizeFund
ItemType : Property
Direction: Get
Data Type: XML
Value: An XML file which describes the available prizes.
Description: The Prize XML has the following format
<Fund>
<Prize>
<Rank>optional parameter describing the tier level of the prize</Rank>
<Name>name of prize</Name>
<Description>description of prize</Description>
<Available>number of these items available to win</Available>
<Info>Free field for storing custom data about the prize</Info>
</Prize>
....
</Fund>
VoucherIssues
ItemType : Property
Direction: Get
Data Type: XML
Value : An XML file describing the vouchers available for issue by this asset
Description: The Voucher XML has the following format
<Vouchers>
<Issue>
<ID>the unique id of this voucher type</ID>
<Name>name of voucher</Name>
<Description>description of voucher</Description>
<Issued>number of these vouchers issued</Issued>
<Limit>the limit to the number of vouchers which can be issued</Limit>
<Info>Free field for storing custom data about the prize</Info>
</Issue>
....
</Vouchers>
User Profile
FirstName
Item Type : Property
Direction: Get
Data Type : String
Value : The user’s first name.
LastName
Item Type : Property
Direction: Get
Data Type : String
Value : The user’s last name.
Photo
Item Type : Property
Direction: Get
Data Type : Movie Clip
Value : The user’s photo if available
Friends
Item Type: Property
Direction: Get
Data Type: Array of Friend Objects
Value : The user’s friends
Description: The Friends property contains all the current friends of the user in the contagion universe this is opposed to the Context friends property which contains a list of all friends that are
ContextFriends
Item Type : Property
Direction: Get
Data Type : Array of Friend Objects
Value : The user’s friends available in that context
Description: The ContextFriends property contains all the current friends of the user which are part of the current context. For instance in a league it would contain all those friends who are part of that league. This is opposed to the Context friends property which contains a list of all friends that are
Friend
Item Type : Class
Description: The friend class is a simple data structure for storing another users details. It comprises of a first name, last name and a photo if that is available.
Properties
FirstName
Data Type : String
Direction: Get
Value : The person’s first name
LastName
Data Type : String
Direction: Get
Value : The person’s last name
Photo
Data Type : Movie Clip
Direction: Get
Value : The person’s photo if available
Data Storage
ContentLocked
Item Type: Property
Direction: Get
Data Type: Boolean
Value: Whether the Content for this context is read only (false) or read/write(true)
Description: The ContentLocked property can be used to determine whether content can be authored in this context. Whether content is locked depends on the nature of the context. In a league of friends playing a game, then the content will be locked otherwise the competition has no meaning. A collaborative group could also exist where the whole purpose is to develop a new content, and in this context the content would remain unlocked.
Content
Item Type : Property
Direction: Get, Set
Data Type: String
Value: Content Data previously stored on the Server
Description: In the case of the content property the Contagion Server does no more than store the data. The string can contain any data in any format, it is up to the digital asset itself to interpret this data.
CreateNewContext
Item Type: Method
Description:
Parameters
Name
Data Type: String
Value: The name of the context to be created.
ScoreRanking
Data Type: Integer
Value: The ranking to be used in this context. (1 Ascending, 0 Descending)
ContextType
Data Type: Integer
Value: The type of context to be created. Current values are
|
Value
|
Name
|
Open to
|
Locked
|
|
1
|
Solo
|
Author Only
|
No
|
|
2
|
Solo Locked
|
Author Only
|
Yes
|
|
3
|
League
|
Author & Friends
|
Yes
|
|
4
|
Collaboration
|
Author & Friends
|
No
|
|
5
|
Challenge
|
Author & Friends
|
Author – No , Friends - Yes
|
ContextData
Data Type: String
Value: The context data to be stored with this context.
Description: The Context data is any information that the digital asset needs to work within the context. The data is stored and retrieved by the Contagion system, however interpretation is left to the digital asset itself and so it can contain any data in any format. This information is shared by all users using this context.
ContentCopy
Data Type: Integer
Value: The id of a context to copy the content item from. A value of 0 will create a blank content item.
Description: For instance a user may author content in a solo context, and then copy that content into a new league context to challenge his friends.
ContextType
Item Type: Property
Direction: Get
Data Type: String
Value: The type of context which is currently open.
Description: The type of context which is currently open.
|
Value
|
Name
|
Open to
|
ContentLocked
|
|
1
|
Solo
|
Author Only
|
No
|
|
2
|
Solo Locked
|
Author Only
|
Yes
|
|
3
|
League
|
Author & Friends
|
Yes
|
|
4
|
Collaboration
|
Author & Friends
|
No
|
|
5
|
Challenge
|
Author & Friends
|
Author – No , Friends - Yes
|
ContextData
Item Type: Property
Direction: Get, Set
Data Type: String
Value: The data for the current context
Description: The Context data is any information that the digital asset needs to work within the context. The data is stored and retrieved by the Contagion system, however interpretation is left to the digital asset itself and so it can contain any data in any format. This information is shared by all users using this context.
ContextUserData
Item Type: Property
Direction: Get, Set
Data Type: String
Value: The user data for the current context
Description: The Context based user data is any information that the digital asset needs to store about the user in that particular context. The data is stored and retrieved by the Contagion system, however interpretation is left to the digital asset itself and so it can contain any data in any format.
GlobalUserData
Item Type: Property
Direction: Get, Set
Data Type: String
Value: The user data which is global for all contexts
Description: The universal user data is any information that the digital asset needs to store about the user which is required in all contexts. The data is stored and retrieved by the Contagion system, however interpretation is left to the digital asset itself and so it can contain any data in any format.
ConfirmClose
Item Type: Method
Description: When the user has made a request to the wrapper that requires the asset to close the wrapper will call the asset API’s Close method. In the process of closing the asset may need to interact with the user, for instance asking the user if they want to save their data. After this interaction occurs the asset should call the ConfirmClose method. The wrapper will then dispose of the asset. If the user decides not to quit the game after all, all the asset needs to do is not call the ConfirmClose method.
Return Value
Data Type: Void
ContextAuthor
Item Type: Property
Direction: Get
Data Type: Integer
Value: The unique player ID of the player who created this context
Tournament Management
PrizeFund
Item Type: Property
Direction: Get
Data Type: XML
Value: An XML file describing the current prize funds available on this game
Description: Prize Fund XML takes the following form
<Funds>
<Draw>
<Events>
<Event> the unique id of the event in the game which causes this draw</Event>
</Events>
<Tiers>
<Tier>
[<Tournament>
<High>The upper rank that this tier applies to</High>
<Low>The lower rank that this tier applies to</Low>
</Tournament>]
<Rank> the rank of the tier being drawn</Rank>
<Prizes>
<Prize>
<Name>the name of the prize to be won</Name>
<Description> A description of the prize to be won</Description>
<Data>Bespoke data about the prize supplied by the publisher</Data>
<Total>Total number of this prize in this tier of the fund</Total>
<Distributed>Number of this prize already distributed</Distributed>
</Prize>
....
</Prizes>
</Tier>
....
</Tiers>
</Draw>
.....
</Funds>
VoucherIssues
Item Type: Property
Direction: Get
Data Type: XML
Value: An XML file describing the voucher issues available in this game
Description: The Voucher XML takes the following form
<Vouchers>
<Voucher>
<Type>The unique type id of the voucher</Type>
<Name>The name of the Voucher</Name>
<Description>A description of the Voucher</Description>
<Count>The number of vouchers issued</Count>
<Limit>The limit to the number of vouchers available for issue (zero or negative values mean unlimited)</Limit>
<Data>Bespoke data about the voucher supplied by the publisher</Data>
</Voucher>
...
</Vouchers>
GetPrize
Item Type: Method
Description: The get prize method is used to cause a prize draw on the server. For security and central control, the control of prize funds must be managed on the server. When an event occurs within the game that requires a prize to be distributed, a request for a prize is sent to the server using encryption for extra security. The server performs a prize draw as configured in the Contagion portal and returns the result code back to the digital asset for display to the user. The process is asynchronous with the wrapper calling the PrizeResult API function on the digital asset when the data returns from the server.
Parameters
EventID
Data Type: Integer
Value: The game event that has caused the prize draw to occur
Return Value
Data Type: Void
IssueVoucher
ItemType: Method
Description: This method sends a request for a voucher issue to the Contagion Server. The server checks the authenticity of the request and the voucher issue limit and then issues the game with a unique trackable voucher id through the VoucherIssued method of the game API.
Parameters
VoucherType
Data Type: Integer
Value: The unique ID of the voucher type to be issued
Return Value
Data Type: Void
Score & Playback
Scores
Item Type: Property
Direction: Get
Data Type: String
Value: An XML file describing the top scores for the particular game
Description: The scores XML has the following structure-
<Scores>
<Score>
[<UID>123</UID>]
<Score>1234</Score>
[<Info>abc</Info>]
</Score>
.....
</Scores>
The Scores tag will contain a configurable number of score tags, the default being 10. The Name and UID tags are present in the League, Collaboration and Challenge contexts (they are unnecessary in solo contexts). The Info tag contains custom data supplied by a digital asset, it can be used for any purpose to extend the functionality of a top scores display.
PlayData
Item Type: Property
Direction: Get
Data Type: String
Value: An XML file describing the play data for the current context
Description: The PlayData XML has the following structure
<PlayDataSet>
<PlayData>abc</PlayData>
...
</PlayDataSet>
If the digital asset stores play data then each score entry in the scores data will have a Game entry in the play data. The contents of the game tag and custom to the digital asset and are not parsed by the contagion system. The typical use of play data is to allow play back of particular games. For instance a player in a tournament may want to see how the current champion does it.
PostScore
Item Type: Method
Description: Score and play data is read only for security reasons. To add to the score data the PostScore method is used. A score must be supplied which the server uses to update the generally available top scores. The other two fields, PlayData and Info can be left blank depending on the functionality required. [See Scores and PlayData properties]
Parameters
Score
Data Type: Integer
Value: The score to be posted
Info
Data Type: String
Value: Additional Information to be attached to this score.
PlayData
Data Type: String
Value: Playback data associated with this scores content
Return Value
Data Type: Boolean
Value: Whether the post was successful.
Subscription Management
GetSubscriptionData
Item Type : Method
Description: Allows an asset with subscription management permissions to retrieve the subscription information on the server. This is returned as an XML file through SubscriptionData method of the SubscriptionManagement API.
Parameters
Password
Data Type: String
Value: The subscription management password set up on the Contagion Server
Return Value
Data Type: Void
SubscribeToGroup
Item Type: Method
Description: Allows an asset with subscription permissions to add the current user to a subscription group.
Parameters
SGID
Data Type: Integer
Value: The unique ID of the subscription group that the player is to be added to.
Password
Data Type: String
Value: The subscription management password set up on the Contagion Server
Return Value
Data Type: Void
UnsubscribeFromGroup
Item Type: Method
Description: Allows an asset with subscription permissions to drop the current user from a subscription group.
Parameters
SGID
Data Type: Integer
Value: The unique ID of the subscription group that the player is to be dropped from.
Password
Data Type: String
Value: The subscription management password set up on the Contagion Server
Return Value
Data Type: Void
SubscribeToGame
Item Type: Method
Description: Allows an asset with subscription permissions to subscribe the current user to a particular game.
Parameters
GID
Data Type: Integer
Value: The unique ID of the game that the player is to be subscribed to.
Password
Data Type: String
Value: The subscription management password set up on the Contagion Server
Return Value
Data Type: Void
UnsubscribeFromGame
Item Type: Method
Description: Allows an asset with subscription permissions to unsubscribe the current user from a particular game.
Parameters
GID
Data Type: Integer
Value: The unique ID of the game that the player is to be unsubscribed from.
Password
Data Type: String
Value: The subscription management password set up on the Contagion Server
Return Value
Data Type: Void
Metrics Capture
InitiateMetrics
Item Type: Method
Description: The InitiateMetrics method needs to be called at the start of each distinct metrics segment. This function tells the server to start a new segment so the subsequent methods record data in the new metrics segment. Metrics methods are additive, in that any calls to the other methods adds data to the relevant part of the metrics recording.
Return Value
Data Type: Void
CloseMetrics
Item Type: Method
Description: The CloseMetrics method needs to be called at the end of each distinct metrics segment to allow the metrics recording to be sent to the server.
Return Value
Data Type: Void
MetricEvent
Item Type: Method
Description: Metrics events are related measurements that are associated with a distinct time. The method adds data to the main metrics recording stream. There are two associated standard parameters, the id of the event that occurred which allows this metric record to be tied to metrics definitions created in the metrics dashboard, and time which allows the events to be correctly arranged in the stream and a timeline to be produced. The data item is made of an XML file which is custom to the particular asset. This XML file is only decoded in the dashboard and remains unanalyzed in the metrics recording system.
Parameters
ID
Data Type: Integer
Value: The event identifier
Time
Data Type: Integer
Value: The time the event occurred in milliseconds from the start of game play
Data
Data Type: XML
Value: The values of any associated measurement with this event formatted in an XML file.
Return Value
Data Type: Void
MetricSpan
Item Type: Method
Description: Metrics spans are related measurements which are associated with a specified time span. The method adds data to the main metrics recording stream. There are three associated standard parameters, the id of the event that occurred which allows this metric record to be tied to metrics definitions created in the metrics dashboard, the time which allows the events to be correctly arranged in the stream and a timeline to be produced, the duration over which the measurements apply. The data item is made of an XML file which is custom to the particular asset. This XML file is only decoded in the dashboard and remains unanalyzed in the metrics recording system.
Parameters
ID
Data Type: Integer
Value: The span identifier
Time
Data Type: Integer
Value: The time the span measurement started in milliseconds from the start of game play
Span
Data Type: Integer
Value: The length of time represented by the span measured in milliseconds
Data
Data Type: XML
Value: The values of any associated measurement with this event formatted in an XML file.
Return Value
Data Type: Void
SegmentMetrics
Item Type: Method
Description: Segment metrics are related measurements which are associated with the whole segment rather than a specific time. The method adds data to the main metrics recording stream. There is one associated standard parameter, the id of the event that occurred which allows this metric record to be tied to metrics definitions created in the metrics dashboard. The data item is made of an XML file which is custom to the particular asset. This XML file is only decoded in the dashboard and remains unanalyzed in the metrics recording system.
Parameters
ID
Data Type: Integer
Value: The span identifier
Data
Data Type: XML
Value: The values of any associated measurement with this event formatted in an XML file.
Return Value
Data Type: Void
Contagion Game World API Reference
Initiate
Item Type: Method
Description: This method is called to let a game asset know that it has the focus and it is time to start interacting with the user. The method also passes in the GameInfo data which is any standard game data which applies to all users and all contexts. This type of data exists to allow digital assets to be altered without a redistribution of binary files.
Parameters
GameInfo
Data Type: String
Value: An XML file describing the game contexts available on this world
Return Value
Data Type: String
Value: An XML chunk describing whether the initiation was successful and any error messages
OpenContext
Item Type: Method
Description: The OpenContext function is the complementary pair to the Wrapper API’s ChangeContext function. When a button/link is clicked in the wrapper, for instance one representing a league, the wrapper will call the OpenContext method in the asset to notify it of the user’s request in the wrapper. Changing context may require a process like a game to be quit half way through, the user may not realise this when they click and the wrapper is not aware of the consequences of the actions. Therefore it is up to the asset to decide whether the context change should be accept, for instance through a dialog box, and pass back whether this context change should be accepted or not. If the a true value is passed back the wrapper automatically loads the new context.
Parameters
ContextID
Data Type: Integer
Value: The identifier of the context to be opened
Return Value
Data Type: Boolean
Value: Whether the context request has been accepted by the game
PrizeResult
Item Type: Method
Parameters
Result
Data Type: XML
Value: The result of the prize draw
Description: When the wrapper function GetPrize is called an asynchronous request is sent to the server. On return of the data from the server, the wrapper calls PrizeResult to notify the asset of the result of the prize draw. The wrapper does not read or interpret the prize draw xml, this is left to the asset.
VoucherIssued
Item Type: Method
Parameters
ID
Data Type: Integer
Value: The unique ID of the voucher issued or -1 if no vouchers are available
Description: When the wrapper function IssueVoucher is called an asynchronous request is sent to the server. On return of the unique voucher id from the server, the wrapper calls VoucherIssued to notify the asset of the this unique trackable ID.
Close
Item Type: Method
Description: The close method lets the asset know that the user has made a request to the wrapper that requires it to close. In that process the asset may need to interact with the user, for instance asking the user if they want to save their data. After this interaction occurs the asset should call the ConfirmClose method. The wrapper will then dispose of the asset. If the user decides not to quit the game after all, all the asset needs to do is not call the ConfirmClose method.
Return Value
Data Type: Void
Kill
Item Type: Method
Description: The Kill method is called when the asset is about to be forced to close and be disposed of. Unlike the close method, the asset will be disposed of directly after the kill method returns. The kill method allows the asset to save data before it is closed, however there is no chance to interact with the user.
Return Value
Data Type: Void
DevZone