To see all content on this site, you’ll need to log in.

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 Locations, 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