Support Post from February 07, 2020
The ProxiCMS API
ProxiCMS is a REST API for Sophatar's content management system (CMS) used for:
- ProxiScreen: contextual and personalized mobile-enabled interactive digital signage
- ProxiHost: location-dependent mobile engagement
All functionality of this API is also available from the ProxiScreen web app.
This API is intended for integration with 3rd party CMS systems, or for programmatic control of content for both digital signage and mobile.
This support post provides a high-level overview. For detailed documentation, pls contact us at info@sophatar.com.
The ProxiCMS API includes:
configuration of your Proxi network (resources:
Beacon
,Kiosk
,Location
)mobile app configuration (resource:
MobileConfig
)uploading of media files of which the uploaded high-resolution versions are used on digital signage and low-resolution versions are automatically created for use on the mobile client (resource:
Asset
)digital signage playout configuration via regulary schedule playout, on-demand playout requests by visitors using the mobile client, and automated rule-driven playout (resources:
CalendarEvent
,Campaign
,Item
,Playlist
,PlayoutRule
,Schedule
,Timeline
)micro-location dynamic mobile app content (resources:
Ad
,Category
,CategoryGroup
,Info
,InfoGroup
,Item
)real-time and historical usage analytics from which you can derive dwell times and foot traffic inside each of your locations, and track visits of the same individual between locations (resources:
Visitor
,VisitorLog
,VisitorPresence
)
- This API documentation refers to a 'mobile client'. This can either be the stock ProxiScreen mobile app, a private-labeled custom version of this app, or any 3rd party app that integrates our mobile SDK.
Each set of functionality is discussed next.
1. Network Configuration
Location
A location is a physical location that is covered by the signal from one or more Bluetooth beacons, either beacon associated with displays (Kiosks
) or standalone beacons (Beacons
).
The mobile client detects the beacons you have configured as part of your Proxi network and then can change its UI and what is shown on nearby kiosks.
You can only edit your locations, you cannot create or delete locations via this API. Locations are created by Sophatar as part of your subscription.
Kiosk
A kiosk is a digital signage display with an associated beacon. The mobile client shows Items
positioned near that kiosk when the visitor is within its viewing range.
When an item has an associated Campaign
, a Visitor
can request on-demand playback of that campaign when tapping the thumbnail for the item in the mobile client.
Beacon
A Beacon resource object identifies a standalone Bluetooth beacon (iBeacon) that you have setup
at any of your locations as part of your Proxi network. A standalone beacon is not associated
with a digital signage screen (a beacon that identifies the location of a digital signage
screen is identified directly on the corresponding Kiosk
resource object).
All configured beacons (from kiosks, or standalone beacons) are detected by the mobile client,
their beacon area entry & exit times logged in the VisitorLogs
, and can trigger unique content
in the app for the visitor when in any of these beacon areas.
Furthermore if a beacon is associated with a Kiosk
, then a visitor can control playback
of signage on that kiosk when within its viewing range (which can be set narrower
than its beacon range).
2. Signage & Mobile
Asset
An asset is an image or video that can show both in the mobile client and on your digital signage.
A single asset can be used on or more Timelines
, as part of one or more Campaigns
that will play on
one or more sets of Kiosks
at your Locations
, either as part of a scheduled Playlist
,
or via a trigger from a nearby mobile client, or via a trigger from the server based on satisifed playout rules.
Category
You can assign one or more categories to each of your Locations
.
These categories show on the mobile client when a Visitor
is within range of
any of the beacons (from Kiosks
or standalone Beacons
) of that location.
For instance you can create categories for 'Drink Specials', 'Food Menu Items' etc
at a restaurant.
A visitor can create an interest profile by tapping categories in the mobile client. The interest profile will be retained and can be used to personalize the content in the mobile client and/or on the digital signage during this or any future visit to the location.
CategoryGroup
A category group allows to combine multiple Categories
under a common
heading, e.g. 'Documentaries', 'Thrillers' could be categories under a 'Movies'
category group
Item
An item is a product or service that you want to promote to Visitors
.
An item is assigned to a single Kiosk
, so as visitors walk around your place
of business they can see different Items in the mobile client depending on where
they are at your place of business (eg. drinks near a bar area in a restaurant,
while food menu items when in a table seating area). Via its association with
Campaigns
, relevant campaigns for that kiosk can be shown, and requested from
the mobile client, when the Visitor
is within viewing range of that kiosk.
3. Signage only
CalendarEvent
An entry on the calendar that spans one or more consecutive days. Currently
the API supports calendar events that are Schedules
(other types of events can
be defined in a future version).
A schedule defines a 24 hr playout schedule for digital signage. Calendar events can get assigned to one or multiple sets of Kiosks
.
Campaign
A campaign is a set of A/V content that plays out together on a digital
signage. A campaign consists of one or more Timelines
, with each timeline playing
in a separate section of the screen.
Playlist
A Playlist is an ordered sequence of Campaigns
. A playlist determines
what is shown on digital signage screens during a specifc timeslot, when its playout
is not overridden by either an on-demand campaign request from the mobile client,
or from rule-based playout, see PlayoutRule
PlayoutRule
Playout rules allow for automated playback of Campaigns
based on certain
criteria, such as demographics and/or interest profiles of detected viewers within
viewing range of a kiosk, historic sales data (top sellers, product recommendations),
or external factors (e.g. weather conditions).
Playout rules can be applied to certain campaigns so their playback becomes contextual, and can be
associated with one or more sets of kiosks. When a rule is satisfied at a kiosk AND a matching campaign
is found AND the kiosk is enabled for rule-based playout, then the regularly scheduled Playlist
is interrupted.
The playout rule syntax is extensible to allow the introduction of additional rules and playout intelligence over time.
Schedule
A Schedule spans a 24 hour period, from 00:00:00AM to 11:59:59PM, and
consists of multiple schedule slots with flexible begin and end times.
Each schedule slot plays a single Playlist
. Schedules can be assigned to one
or more consecutive days and to one or more sets of Kiosks
by using CalendarEvents
.
Timeline
A Timeline is an ordered sequence of Assets
. A Timeline defines the
A/V content that will show in one zone of the screen as part of a Campaign
.
Depending on the configuration, the layout of the zones on the screen is either
hardcoded in the signage presentation template locally on the media player, or
can be set dynamically from the layout specified in the campaign.
4. Mobile only
Ad
Your location-dependent ads. An ad can be assigned to one or more Location
s,
and shows on the home screen of the mobile client when Visitors
are within the
beacon range of any of these locations.
Info
To each of your Locations
you can assign one or more Infos.
Together with the location-dependent Ads
, infos show on the home screen of the mobile
client when a visitor is within range of any of the beacons (both from Kiosks
and standalone Beacons
) at that location.
Use Infos to provide general information about our place of business (eg location of ATMs, restrooms etc).
Furthermore each info by itself optionally can have one or more details associated with it that show in the mobile client when the visitor taps on the info icon. Each of these details are called 'posts'. For instance for a 'Reviews' info, each post would be an individual review.
InfoGroup
An info group allows to combine multiple Infos
under a common heading,
e.g. 'ATM', 'Restrooms' could be provided under a 'Directions' group.
MobileConfig
This resource allows customization of the mobile app. Currently you can change the content shown on the home screen of the mobile app when the visitor is not at any of your beacon-enabled locations (via other resources in this API you can configure all content that shows in the mobile cleint when the visitor is within any of your beacon areas). This allows for dynamic updates to the home screen and provides a primary real-estate in the mobile client to promote your business in case of a ProxiHost virtual concierge application (where the app customizes to any of your advertisers when in their respective beacon areas but shows your content outside any of these areas).
You can only edit customizations of sections of the mobile client. You cannot create or delete customizations.
Note that the complete look and feel & branding of the app is not customized by this resource but can still be completely updated by Sophatar in either our standard Proxiscreen mobile app, or your private-labeled version (eg. to show a Holidays theme during the holiday period) since we can push a complete UI update in the background to all current and future mobile app installs. We can do this without the user having to download a new version of the app from an app store. If you would use only our Proxi SDK, then any complete UI customization would have to be handled on your side.
5. Analytics
Visitor
This resource allows to lookup profile information of visitors based on either real-time visitor information
at any of your locations (from VisitorPresence
) or historical visitor information (from VisitorLog
).
Profile information includes the email address a visitor signed up with in the mobile client,
any additional information they entered on their profile (name, gender, age range, phone#),
and the interest profile created from tapping Category
icons in the mobile client. If using other components
of the Proxi.VIP platform that ingest sales data, we can also link a visitor profile with individualized
sales data.
This resource is read-only via this API.
VisitorLog
A log is created for every detected entry and exit of a Visitor
in a beacon range of your Kiosks
& Beacons
.
A separate timestamp is recorded for each entry & exit. From this you can derive dwell times of each visitor
in each beacon area, and traffic inside and between your locations.
This resource is read-only. Returned data can be filtered by location and/or time range.
VisitorPresence
This resource provides real-time data of visitors currently at any of your locations. You can retrieve each visitor's stats in terms of their number of location visits, number of kiosks/beacons they have been near to, dwell times, and number of on-demand signage requests. This resource is read-only. Returned data can be filtered by location.
Interested to find out more? Contact us at info@sophatar.com