Configure the server

To use the web service, you must configure it in the master.config file of the server. Before you do so, consider the following requirements:

• You must configure the master.config file for all individual customers.

• You must configure a valid Security:SymmetricSecurityKey as shown in the example below.

To configure the AdServing API, perform the following steps:

1. Open the master.config file of the server.

2. Configure the following settings:

   • SSP_URL: Specify the URL of the SSP. That is, the external booking platform.

   • SpotGroupName: Specify the  name of the spot group to which the media files downloaded from the SSP are uploaded as spots.

   • ServiceUserName: Specify the name of the user who uploads the spots and adds them to the playlist.

   • PlaylistName: Specify the name of the spot group to which the media files downloaded from the SSP are added as spots.

   • ExtendSpotValidityInDays: Specify how long uploaded spots are valid in days. For example, enter 0 if the spot is valid indefinitely or enter 1 if the spot is only valid today. The default value is 0.

   • MaxLogLevel_File: Optionally, enter the maximum log level to specify which kind of information you want to log once for all customers:

     • 1 for Error

     • 2 for Warning

     • 3 for Info

     • 4 for Debug

     • 5 for Trace

Note on logging

If you need additional Microsoft logs for debugging or further insight, you can optionally set logging to “Warning”, but we recommend setting it to “Critical” in general to avoid performance issues.

Example: configuration of the master.config file

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<configuration>
  <appSettings type="global">
    <add key="Security:SymmetricSecurityKey" value="INSERT-A-KEY-HERE" />
  </appSettings>
  <appSettings type="AdServing">
	<add key="AdServing:Customer:dev:SSP_URL" value="http://ads.ooh.digital/adserver.php?nid=S2AD&pid={boxId}"/>
	<add key="AdServing:Customer:dev:PlaylistName" value="SSP"/>
	<add key="AdServing:Customer:dev:SpotGroupName" value="SSP"/>
	<add key="AdServing:Customer:dev:ServiceUserName" value="admin"/>
	<add key="AdServing:Customer:dev:ExtendSpotValidityInDays" value="1"/>
	<add key="MaxLogLevel_File" value="3"/>
  </appSettings>
</configuration>

To use the AdServing API web service, you must configure the master.config file of the server and a customer specific SSP config file.

To do so, perform the following steps:

1. Open the master.config file of the server.

2. Go to the setting AdServing:Customer:<CUSTOMER-ID>:SSP_CONFIG and specify the path to the customer specific SSP config file.

3. Optionally, specify the following general settings in the master.config file:

   • AdServing:DownloadWorkerIntervalMs: Specify the interval for checking for new media files that must be downloaded and imported into the IXM Platform in milliseconds. The default value is 1000 ms. If you specify less than 0 milliseconds, the AdServing API stops working.

   • MaxLogLevel_Console:Enter the maximum console log level to specify which kind of information you want to log:

     • 1 for Error

     • 2 for Warning

     • 3 for Info

     • 4 for Debug

     • 5 for Trace

   • MaxLogLevel_File: Enter the maximum file log level to specify which kind of information you want to log:

     • 1 for Error

     • 2 for Warning

     • 3 for Info

     • 4 for Debug

     • 5 for Trace

Note on logging

If you need additional Microsoft logs for debugging or further insight, you can optionally set logging to Warning, but we recommend setting it to Critical in general to avoid performance issues.

Example: configuration of the master.config file

<appSettings type="AdServing">
    <add key="AdServing:Customer:27:SSP_CONFIG"
    value="\\gfstor002.grassfish.local\GFServers\Server\01\configs\ssp-config-27.json"/>
    <add key="AdServing:DownloadWorkerIntervalMs" value="1500"/>
    <add key="MaxLogLevel_Console" value="5"/>
    <add key="MaxLogLevel_File" value = "5" />
</appSettings>

Configure SSP parameters

You must configure the SSP parameters like the SSP’s URL in the SSP config file. The file has the following structure:

{
 "sspConfigurations": [
    "sspConfiguration": {
        "sspPriority": int,
        "sspUrl": string,
        "cutMediaUrlBeforeSubString": string,
        "sspRequestHeaders": Dictionary<string, string>,
        "sspCategoryId": int,
        "sspPlaylistId": int,
        "sspSpotGroupId": int,
        "sspServiceUserId": int,
        "extendSpotValidityInDays": int
    }
  ]
}

Get the IDs

Before you can configure the SSP config file, you need to get the IDs of the IXM Platform category, playlist, spot group, and SSP user for each SSP. You’ll enter these IDs in the file.

When the system uses IDs instead of names, you can simply change the names of playlists or spot groups in the IXM Platform without affecting the ID and SSP. This also means that the same SSP admin user works for multiple SSP providers.

To get the IDs, perform the following steps:

1. In the IXM Platform, open the editing window of the category, playlist, spot group, or user whose ID you need.

2. Open the Developer Tools in your browser. For example, in Google Chrome go to Customize and control Google Chrome > More Tools > Developer Tools.

3. In the Developer Tools window, select the Network tab.

4. Read the ID from the list and write it down for the file configuration in the next chapter.

5. Repeat steps 1 through 4 until you have the required IDs of the category, playlist, spot group, and user.

Ensure that your configuration is valid

Your configuration is validated with the help of validation rules. If one or more of these validation rules are violated, the AdServing API logs an error message and stops.

The following rules apply:

• Multiple sspConfiguration elements within one file must not contain the same values for: SspPriority, SspUrl, and SspCategoryId. Ensure that these elements have different values in the config file.

• None of the specified configuration parameters must be missing. This excludes the optional parameters CutMediaUrlBeforeSubString, SspRequestHeaders, and ExtendSpotValidityInDays.

• All specified configuration parameters must have a value.

• None of the specified configuration parameters must have a value that doesn't match the specified data type.

• The basic syntax of the JSON must be valid.

Configure the config file

To configure the SSP parameters in the SSP config file, perform the following steps:

1. Open the SSP config file.

2. Specify the following settings:

Example: configuration of the SSP config file

{
	"SspConfigurations": [
		{
			"SspPriority": 1,
			"SspUrl":"https://test.grassfish.tv/testdata/ssp/units/",
			"CutMediaUrlBeforeSubString": "?",
			"SspRequestHeaders": {
				"hs-auth": " api-key 1234567890"
				},
			"SspCategoryId": 1593,
                     "SspPlaylistId": 259,
			"SspSpotGroupId": 958,
			"ExtendSpotValidityInDays": 3,
			"SspServiceUserId": 1489
		},
		{
			"SspPriority": 2,
			"SspUrl": " https://test.grassfish.tv/random/ssp/schedule/",
			"CutMediaUrlBeforeSubString": "?",
			"SspCategoryId": 1592,
			"SspPlaylistId": 263,
			"SspSpotGroupId": 957,
			"ExtendSpotValidityInDays": 3,
			"SspServiceUserId": 1489
		}
	]
}