Import tool – Catalog Service API

1. Go to Admin → Utilities tab → Imports.

2. Click Create Import.

3. Fill in the following details:

   • Import Name

   • Account (with “Imports” enabled)

   • URL (Paste your public CSV URL)

4. Under Repeat, set how often the system should check for updates (in minutes)

5. Under Field Mapping, enter the column names you want to display (relevant only if need to override the column header name to custom value)

6. Important: Under the Grouping tab:

   • If you do not have values for Start Date and End Date, do not select anything under the Date Format field.

7. Set the Time Zone (used only with Date/Time. Not relevant for other cases)

8. Click Save.

9. After saving, a Custom API URL will be generated under the Import Info page. Open it to verify that your data is visible.

Once your catalog is created, you can retrieve items using the Catalog Service API. There are two main types of data you can access: Regular Items and Event Items.

A. Accessing Regular Items

To get standard catalog entries, use the following endpoint:

Path Parameters

• {studio-domain} – Your dedicated NoviSign Studio domain.

• {account} – The account ID associated with your integration. Find this in Studio Settings or the Admin Console.

• {itemsgroup} – The main grouping key for your data (e.g., “Channel name” in Zapier or “Import name” in Imports).

Optional Query Parameters

• group2 (String) – Filter items based on an additional grouping configured in Import settings.

• sortBy (String) – Determines how results are sorted:

  • itemId (default)

  • created (by record creation time)

• reverse (Boolean) – Set to true to reverse the sort order.

• idForName (Boolean) – If true, item keys will use the actual itemId values. If false (default), keys are numbered incrementally (0, 1, 2, …).

B. Accessing Event Items (Time-Based Records)

For retrieving events with start and end times, use this endpoint:

Path Parameters

• {studio-domain} – Your Studio domain.

• {account} – The account ID used for the integration.

Required Query Parameters

• group1 (Array[String]) – Primary grouping key(s) representing your integration channel (e.g., “Channel name” in Zapier). Multiple values allowed.

• group2 (Array[String]) – Secondary grouping key(s) for filtering (from Import settings). Multiple values allowed.

• sortGroup (Number) – Sort level:

  1. By group1

  2. By group2

  3. By group3

Time-Based Parameters

• startTimeShift (Number) – Offset the current time by minutes (negative for past events).

• endTimeShift (Number) – Extend the time window beyond the current time (in minutes).

• filter (String) – Filter events by timing:

  • current – Ongoing events

  • future – Upcoming events

  • Leave blank or null – All events

• untilEndOfDay (Boolean) – If true, retrieves all events until the end of the current day.

Optional Header for All Requests

• X-API-KEY – Use if additional security is required. This header is optional and can be requested from your account administrator.

Once your catalog data is set up, you can configure your player to fetch and display this data dynamically using Custom API Integrations.

A. Setting Up a Custom API Integration

1. Navigate to:
   Settings → Advanced → External Interfaces → Custom API Integration

2. Create a new integration and complete the following fields:

   • Name: Give your integration a clear, descriptive name.

   • API URL: Enter the URL from which JSON data will be fetched.

   • Refresh: Set the refresh rate in seconds. Choose a value that balances data freshness and performance.

   • Request Type: Select GET (default) or POST depending on your API.

   • Request Body and Headers: Add any required parameters, such as static tokens. Leave empty if not needed.

   • Property Key: Choose a unique key. This key will be used in Studio to inject dynamic data into your creatives.

3. Validate: Click Test to verify your configuration. If successful, the JSON payload will display on the screen.

4. Save: Click Save to store the integration and proceed to assign it to your content.

B. Custom API Integration via Screen Content (Android Only)

For Android players, the Screen Content Configurations module allows you to configure and export Custom API integrations directly within Studio, avoiding individual device setup.

Steps:

1. Navigate to:
   Screen Content → Settings → Configurations → New Configuration → External Interfaces → Custom API Integration → Click To Change

2. Create and test the new configuration.

3. Assign the configuration to specific screens:

   • In Screen Content, click the three-dot menu for a screen → Set configuration

   • Once applied, the player will automatically import the configuration when that screen is selected for playback.

C. Using Dynamic Variables in Studio

In Studio, dynamic content is displayed by using variable expressions that reference the API data at runtime.

Syntax Format:

• ${@customapi}: Reserved prefix indicating JSON data reference.

• PROPERTY_KEY: The property key defined in your Custom API Integration.

• JSON_KEY1, JSON_KEY1_1, …: Inner paths within the JSON structure containing your data.

Example:

JSON response:

With property key set to myrestaurant, the path:

will display 1031 in the widget.

D. Supported Widgets

The dynamic variable syntax works with:

• Text

• Label

• Webpage

• Web Video

• Web Image

These widgets will automatically populate data from your API at runtime.