xamoom connects physical places and real life objects with content items. This means xamoom is basically a location based service platform, but it does not only use your location to identify what to do. So, let's call it a context based service platform.
- Connecting things and places
- Access Interfaces, Markers, Spots & how to find the right Content
- API Keys
- Never hardcode ids!
- Date and time values
xamoom uses so called markers to connect a physical place or object with its digital representation - the spot - which is connected to a page. In the API, pages are called content. The reason for this is that although content items look like pages on the web, this is only the way it is shown to the user. Technically, they are containers for so called content blocks, which contain various types of data.
A Marker is a container for multiple Access Interfaces. A Marker for example can be a label in a gallery next to a painting. On this label we find a QR Code and a NFC tag, which are the Marker's Access Interfaces. The Marker defines that the QR Code and the NFC tag belong together as a unit to identify an object.
Another example could be an iBeacon. This would be a Marker with only one Access Interface. The iBeacon identifies itself with its unique id and that's it.
All these Access Identifiers have one thing in common: They somehow contain a unique id. In the case of QR and NFC the id is wrapped into an URL on the code or chip and get's generated by xamoom to keep it unique inside the whole system. These URLs look something like this:
"foobar" in this case is the unique id of this Access Interface, this is called a location identifier. In the case of an iBeacon the location identifier would be the unique id of the beacon. These identifiers are used to identify the Marker on the backend.
There is also a special kind of Access Interface called custom. This is a string that a user can add to a marker. IT can contain basically every character and is not fixed in length. For you as a developer, this doesn't really make a huge difference since you can use them like every other location identifier.
Markers are assigned to Spots. Spots are the digital representation of a physical object or place. So let's continue with our museum example and call this spot "Exhibit 1". Each Spot can have multiple Markers assigned to it.
Each Spot is assigned to a Content (Page). This connection is dynamic, which means that a customer could switch the content assigned to a Spot simply by editing this assignment on the web admin interface at xamoom.net or by assigning a condition to the spot, which results in diefferent content items on spot based on certain conditions. This dynamic connection allows us to quickly change the Content that an enduser receives according to changed circumstances. So let's assume that our marker is assigned to the spot "Exhibit 1" and the location identifier "foobar" is on one of it's access interfaces. If this location identifier is used to get the content, the backend will find the Marker by the Access Interface with this location identifier bound to it, get the Spot this Marker is assigned to and then return the content that is currently assigned to the Spot.
As mentioned earlier a Content, referred to as a Page in the admin web client, is a container for other objects. In detail a Content item consists of a list of languages, which contain another list of all ContentBlocks for each language, and also some data that is the same in every language, like the cover image. Every time you query the backend for a Content item you will also have to specify in which language you want the Content item to be. This language can be read for example from the users browser settings or from the language a user has chosen on his smartphone. The backend will then return the content in the desired language, if this particular Content exists in this language, or in the default language specified by the admin, if this Content does not have this language.
We've already discussed how we can receive a content that is bound to a Spot by using a location identifier, but there is also another way how we can get a specific content item. We can use its content id. This id is generated for every Content item and is unique across the system. With this id you can send a request to the backend, also including the desired language, to receive a Content item without the need of a Marker or Spot. This is the way that is used in the wordpress plugin, where we have no need for Spots and Markers.
As already mentioned a Content includes a list of ContentBlocks for each language. These blocks are abstract definitions of multimedia items. They can be as simple as text, but can also contain for example a youtube URL, which means that if you want to display this block on a website you should render a Youtube Player, that plays exactly this video, and also more complex types like a so called SpotMap which requires a second API call to get the Spots that match the parameters defined in this ContentBlock and then for example show them on a Map on a website or in an app.
For each and every API call you need an API key. These keys are bound to a system, which means that you can only access data of your system with your key. If you try to access a Content item of a different system, the call will fail. You can find your API key by logging into you xamoom system on xamoom.net. There you go to the Start and on the right side panel you'll find your API key. If you can't find it there, please contact us.
This is very important! Never ever hardcode any Id in your application. Not even the one of your system. Always use your API key to get your system, without id and from there on use the relationships to get objects like Style or Settings. Also never hardcode Content Ids, always query for them by tags or use location identifiers to get content that is connected to a place or object. This will make your life a lot easier and makes your solution a lot more flexible.
This is very important! All dates that you will reveive from the API are in UTC. So you have to convert them to the user's local time. Also if you use timestamps to query for something you have to use ISO8601 format and convert the local time to UTC, before sendig it to the backend.
- Example in correct format: 2007-12-24T18:21Z