Repository navigation
Concepts
With this document, we'd like to give you an overview of the concepts and "business objects" available in our APIs. This is important, because you can find more than one way to achieve your goal, but there's only one optimal way to do it, as with any API.
- Domains
- Virtual FS
- Game VFS
- Properties
- Indexing
- Leaderboards
- Transactions
- Achievements
- Matches
- Products
- Events / notifications
- Batches
- Hooks
- Timers
Domains are extensively used in our APIs. They're a kind of scope for your data. Domains have one interesting property: they can optionally be shared between games, allowing data exchange.
Almost everything in our APIs is scoped by Domains. Most often, you'll simply use the "private" domain, which scopes data to the current game. The private domain can't be shared.
So, if you don't need sharing, you don't have to worry about domains: use "private". Otherwise, you can create a new domain at https://account.clanofthecloud.com/ and share it between your games. It's name is random...
It's actually a Key/Value kind of storage, private to the current player. It's optimized to store modest amounts of data in it (say <100ko sounds best). For much bigger data, you can rely on our S3 storage system (where only an S3 URL is stored in the key).
Use the Virtual FS for data related to the current gamer, except if it suits another "business object" better.
Virtual FS cannot be shared between players, but it can be shared between games (same player).
It's a Key/Value storage, private to your game. Use it to store constants, translations, etc... It's immutable (you can't update it with the API, only from the Backoffice application) so it's quite safe to use. Also, keep your data small enough (<100ko sounds ok).
If you need to store large assets (graphics, levels), use the S3 interface instead...
This is really data attached to a user, used mostly to describe the user: his rank, his war-name... It's not designed to change very often.
Sometimes, you need to search for something: users, matches, whatever. For that, we have a very generic indexing API. For instance, you could index users by rank, to allow searching for users by rank... or index matches by rank/map. The indexing API allows multi-key searches, sorting, etc...
Indexing allows very complex kinds of queries, like geographic queries... Contact us if you have such an advanced requirement and we'll help you implement it (it's not really easy).
Leaderboards store users' scores, and allow to retrieve best scores, users' scores, and even score pages centered around the user. Leaderboards are also dynamic: you don't need to create them beforehand, just post a score and the leaderboard will be created.
Transactions are really transactions, that modify a Balance. A Balance is a kind of K/V storage, limited to positive numeric data. It can't be modified directly: modification can only happen through a transaction, which says which key should be adjusted, and by how much.
So a Balance is perfect to keep track of inventory, or resources, or money.
For instance, a balance could be {Gold: 10, Arrows: 40, Wood: 30000}... A transaction can modify more than one key at once: a transaction to decrement Gold by 5 and increment Arrows by 10 is {Gold: -5, Arrows: 10}.
Achievements are linked to transactions. You can't just trigger an achievement, because our achievements are automatic: you define them as a rule compared to a balance (Gold > 1000), and a reward (Bomb: +3). Each time you send a transaction, achievements are checked and automatically applied.
Please note that a consequence is that if you want to use achievements, you must use transactions!
Events are messages sent to a player asynchronously. They offer a very strong "at least once" delivery guarantee, which is used by the system to signal events to players, but you can also use them in your game. They are not "real time" events delivered on a lightweight protocol like UDP, but more robust (and slower) messages.
Push notifications are implemented as a special case of events. With ClanOfTheCloud, you can't send a push notification directly: you send an event (which can be handled by the game if it's running), with a fallback Push Notification message. If the event is not handled (player is offline) a push notification will be sent to the player's mobile phone.
The match system provides a way to offer matches within players, and for them to seek for games using various criteria. Matches represent a centralized game state stored on our servers, updated on a turn-basis by making "moves". These moves would be notified to other players, along with the ability for them to join an ongoing match. Therefore, it is suited for all sorts of turn by turn games, but not recommended for real time games such as MMORPGs, which may require a more sophisticated logic to be handled on your servers.
We offer services that make it much easier to provide in-app purchases within your game on supported platforms, while maintaining a familiar and reassuring user experience. That means that the purchases are made through the AppStore on iOS or Google Play on Android for instance. The actual purchased items are securely recorded on Clan of the Cloud and can be credited to the gamer's balance using a transaction that is triggered upon verified purchase.
Batches and Hooks (see below) have a lot in common: they're Javascript code you write to run on our servers.
Batches mostly allow grouping many operations in a single call to our servers for performance and implementing game logic on servers to limit game hacking.
Batches give you the freedom to develop your own server-side logic, with the scalability guarantees of ClanOfTheCloud. Batches have a direct access to our APIs (sandboxed to your game).
Hooks are similar to batches, but they are JS functions that get called when various API calls are made. Many APIs have a 'before-' and an 'after-' hook, which make it very easy to either check parameters (implement specific security rules), or keep data synchronized (indexing data after adding it for instance).
Hooks have the right to break an API call. For instance, you can decide that some VirtualFS keys should never be written to directly, but instead should always go through a batch (which will check security rules).
When designing games, sometimes, things must be timed, like a construction should take 5 hours, should and continue offline, and should change something in the game's data after it's completed. Timers allow just that. They let you run a batch in the future, list the scheduled timers, delete a timer, retime a timer... With timers, implementing a game when the world never stops is easy.