What Is the Content API?
The Content API provides a powerful and flexible way to manage digital signage content programmatically. Designed for seamless integration, it allows businesses to automate content uploads, playlist management, scheduling, and more.
Key Features
- Easy Integration: Use a GraphQL interface to retrieve and manage content efficiently.
- Automated Content Management: Upload media files, manage playlists, and schedule content programmatically.
- Flexible Scheduling: Set time-based rules for content display.
- Structured Media Library: Organize and retrieve media files effortlessly.
How It Works
Using the Content API, you can:
- Upload Media: Securely upload images and videos to a centralized media library.
- Create Playlists: Organize media files into playlists for structured content display.
- Schedule Content: Define time slots for when content should be displayed.
- Manage Content: Update, remove, or reorganize media with ease.
Getting Started
To begin using the Content API:
- Ask for access to the API: Contact our support to get the API enabled on your account.
- Obtain an API Key: Authenticate your requests using a provided API key.
- Access the API: Use the API endpoint to interact with your digital signage content.
- Integrate with Your System: Automate and customize content management according to your business needs.
For in-depth technical details, refer to the Technical Documentation.
Content API Technical Documentation
Generate an API key
First, we require an API key. Each user has their own API key which can only be viewed once when generating it.
You can generate an API key by navigating to your personal settings (click your avatar on the top right in PLAYipp, then personal settings).
Go to API keys page. Click Generate API Key, copy the generated key and give it a name to it's easy to keep track of things.
Introduction
The Content API allows developers to programmatically manage digital signage content using GraphQL. This documentation provides details on authentication, queries, mutations, and usage examples.
Authentication
To use the API, include your API key in the request header:
API Endpoint: https://signage.playipp.com/api/public
Uploading and Publishing Content
1. Request an Upload URL
Our first use case will be fairly simple; uploading and updating a file via the API that will go to your screen.
In order to publish a file to a screen, there are a few requirements.
We need to include our API key in all our requests, so we require a header which includes our API key.
This header should have a key called “Authorization” with a value of “Bearer API key”. Replace the text API key with your actual API key you got earlier.
Next, we need to actually upload the file to a PLAYipp fileserver, which we can then use to send the file to our PLAYipp media library before publishing it.
First, we wish to create an upload URL which we do by running
in GraphQL towards https://signage.playipp.com/api/public.
What returns is a URL which is the fileserver we wish to use.
NOTE: This URL will be valid for a long time, so no need to worry about that for now, although it would be useful to check what the return code is, and create a new upload URL if we do not get a valid response back from the fileserver.
This is where we publish the file itself. What we wish to send now is a query towards the URL that returned with a multipart or form-data encoding. The key name should be “filename” whilst the value should be the location of your file.
NOTE: Links will not work here (e.g. SharePoint link), this needs to be an actual location on your disk.
Now that we have uploaded the file to our fileserver, we want to transfer that file over to the media library. The return value from our previous query is the ID of the file in the fileserver, so make note of this or copy this.
However, there is one variable we need to acquire before can do that, which is folderId. FolderID is the ID of the folder in our media library we will store it. If you do not already have one, you will need to create it in the platform.
In order to get our folderId, we will need to run:
We can also target the specific folder if you have several folders by defining “folderName: “myFolder”” instead of folderId: null if you wish to target a specific folder.
The response will be list of folders and the media located underneath each folder.
What we want here is the “id” that will be towards the top of the result, make sure it matches the name of your folder. We will use this ID in the next query.
Our next query will be to transfer from the fileserver to the folder in the media library and will look like this:
NOTE: Priority options here are BACKUP, STANDARD and PRIORITY. Backup will always play last, whilst priority will always be first. Standard will play after priority, and before backup.
What we get in return is a new id, namely objectId. We will need this in a bit, so make note of this or store it.
The actual next step would be to publish this media file to the playlist of the screen, however we need to target the actual screen. We do this by targeting the layer and location of our screen, so we need to fetch some id’s before we can actually do that.
First, let’s run:
Depending on your PLAYipp setup in the platform, this can return one or several, depends on how many locations you have. Find the name of the location your screen is located on, and store it’s ID.
Next, we need to find our layer, however to do that, we need to know which layout it is using.
With that, let’s run:
Find your relevant layout here and store it’s ID.
Now that we have acquired our layoutId, we can use this to find the specific layer we want to target in the layout.
Let’s run:
Again, find the relevant layer (name is probably the way to go here) and store it’s ID.
Now that we have our locationId, layerId and objectId (the return value of our createMediaObject) we can publish the file to the playlist and have the file up and running in 2-3 minutes.
To do this, we run:
NOTE: If length is not defined, a default value of 10 seconds will be applied. The length of a video will be the actual length of the video uploaded.
Nice, now our file should be uploaded to the playlist and be on the screen promptly! You can verify this yourself if you navigate to Signage, then Publish and locate the screen we have posted it to. The actual transference of the file in PLAYipp is instant, however it takes a little bit of time for the screen to notice there is a new file, download and start displaying it.
If you want to change the file we just uploaded to a new file, store the playListItemID that returns.
Now, let’s say we want to do two things. The first is to upload another file. In this case, we need to publish our file again to the fileserver and then to our media library, use the ID that returns with createPlaylistItem with the same location and layer ID that we just used (unless you want to post it somewhere else).
What about changing the first file that we uploaded to a new one?
For that, we must first have it on the media library, so refer to our earlier queries about first uploading it to the fileserver and then to our media library.
Now that we have it in our media library, we can target the file with a new query, updatePlaylistItem.
If you did store the playListItemID, we can use that to target which item in the playlist we want to replace with our new file.
The query goes as such:
With this query, we do not require location or layer ID, just the playListItemId and objectId.
NOTE: If you did not store the playListItemId, you can fetch this by running:
With this query, the field “id” will be your playListItemID.
So that was how to upload and update a file to a screen with PLAYipp API.
There might be many steps, however this can create good dynamics and alternate functions that would otherwise not have! If you prefer to upload all your files in one go, you can do that before you start uploading them all. Maybe you want some of the files to be in another layer or another location, etc.
This is the bread and butter of the Content API, and in other articles we tackle things such as removing files from the media library and from the playlist as well as creating and removing a schedule.
If you wish to remove the file from the playlist or media library, you can make use of these queries:
Schedule Creation and Deletion
Many wish to have their files for a specific duration, like only showing it for a week or only showing it on mondays, etc.
This is fairly simple, the way schedule works is that it is attached to a specific playListItem. If you have read through the article for uploading and updating a file, you might be familiar with playListItem already. However, for this article we will assume that you are not for clarification purposes.
The use case goes as follows.
We have a file that is playing 24/7 on a screen, and we want to create a schedule for it to only play on weekdays between 08:00 - 16:00, as well as having it expire in a month from the date 01/04/2025.
In order for us to create a schedule, we need the playListItemId. If you do not want the procedure of getting the playListItemId, please click here to skip to creating the schedule.
In order to find our playListItemId, we need to run the PlaylistItems query, which requires a locationId and layerId.
First, we’ll get our locationId by running:
Find the location that you wish to target if you have several by matching it’s name, and extract the id.
Next up, we require our layerId, however to do that we need to find the layoutId in order for us to find our layer.
Let’s run:
Again, match the name with the layout you want to target, and extract it’s id.
With that stored, we can now run:
We now have all the required ID’s which will allow us to run:
Which gets us a list of our media files in the playlist we have targeted. Locate the file you wish to post a schedule on and extract it’s id.
With that out of the way, we can now create a schedule on the media file.
We have now successfully created a schedule for our file which will only play on weekdays from 08:00 - 16:00 and will expire a month from 01/04/2025.
If you wish to create a new schedule for it, simply run this query again to update the relevant schedule to the file. It will always use the latest published schedule.
If you wish to remove the schedule, extract the id from the return of the previous query, or list the schedules with a query to find the relevant schedule:
In order to get it’s id if you need it, and then run:
Notes
- The priority field supports STANDARD, BACKUP, and PRIORITY values.
- Playlist items are published and active upon creation unless specified otherwise.
- The length field is automatically set for video uploads.
This document serves as a reference for developers integrating with the Content API. For broader implementation guidance, refer to the productized API documentation.