Requesting UDC data

Requesting dynamic data via the UDC interface is simple with the gfUdcConnector. Use the following instructions to integrate the connector in HTML Basic and HTML Wizard spots.

Including the library

The gfUdcConnector is embedded in the index.html page via the „script“ tag, e.g.: <script src="PATH_TO_SCRIPT/gfUdcConnector.js"></script>

Instantiating the gfUdcConnector

In order to allow the invocation of the gfUdcConnector function, it must be instantiated within the particular code prior to this:

var udc = new GFUdcConnector();

udc.getVersion();

Object typification

UDC data objects

In order to better illustrate the structure of the data, individual objects are typified and used for descriptions of functions in the following sections.

UdcData

UdcData: {
   Success: boolean,
   Result: DataSource[]
};

UdcDataByKey

UdcDataByKey: {
   Success: boolean,
   Result: DataSource
};

DataSource

DataSource: {
   Categories: Category[],
   ContainerGuid: string,
   Elements: Element[],
   Key: string,
   LastModified: string,
   PluginInstanceName: string
};

Category

Category: {
   ExternalId: string,
   Id: number,
   LastModified: string,
   MediaFiles: any[]
   Name: string
};

Element

Element: {
   CategoryIds: number[],
   ElementValues: any[],
   ExternalId: string,
   Guid: string,
   Id: number,
   LastModified: string,
   MediaFileBaseUrl: string,
   MediaFileDirectory: string,
   MediaFiles: any[],
   Name: string
};

MediaFile

MediaFile: {
   Image: string 
};

Debug objects

The determination of the parameters required for the test connection is described in detail in Setting up a UDC test connection.

DebugServer

DebugServer = {
   url: string,
   locationId: number,
   spotId: number,
   sessionId: string
};

DebugClient

DebugServer = {
   ip: string,
   siid: number
};

DebugFile

DebugServer = {
   url: string
};

Available features

getData

By means of this function it is possible to retrieve all UDC data connected to the spot.

Parameters:

{callback} onSuccess: returns UdcData, result as plain text {string}
{callback} onError: returns error message {string}

Example:

var udc = new GFUdcConnector();
udc.getData(function(jsonData, plainData)
{
   // data as JSON {UdcData}
   console.log(jsonData);
   // data as plain text {string}
   console.log(plainData);

}, function(message)
{
   console.error(message);
});

Explanation:

The getData function is assigned with two call-back functions. If successful, the first function is invoked with the UdcData object and data as a string (see UdcData). In case of an error, the second function is invoked with the error message.

UdcData.Result is an array of DataSource objects which relate to the data sources which are linked to the spot or spot instance. Depending on how many data sources are assigned to the spot or spot instance, the number amounts to 0..n objects.

The individual data sources then must be identified via the description of the data source (key) and processed accordingly.

getDataByKey

By means of this function it is possible to request a specific data source via its unique description.

Parameters:

{string} key: unique designatorht

{callback} onSuccess: returns UdcDataByKey, result as plain text {string}
{callback} onError: returns error message {string}

Example:

var udc = new GFUdcConnector();
udc.getDataByKey("News", function(jsonData, plainData)
{
   // data as JSON {UdcData}
   console.log(jsonData);

   // data as plain text {string}
   console.log(plainData);

}, function(message)
{
   console.error(message);
});

Explanation:

In addition to the unique description of the data source, the getDataByKey function is assigned with two call-back functions. If successful, the first function is invoked as a string with the UdcData object and data (see UdcData). In case of an error, the second function is requested with the error message.

UdcDataByKey.Result is a DataSource object which relates to a data source assigned to a spot or spot instance. If a data source cannot be found via its unique description, it is UdcDataByKey.Result undefined.

setLocalTestData

By means of this function it is possible to test a spot against various UDC web services and goals during development. The parameters of the individual connection types must be set correctly in order to ensure the error-free operation of the interface.

Parameters:

{DebugServer|DebugClient|DebugFile} connection

Example:

var udc = new GFUdcConnector();
var connection = {
   ip: "192.168.169.73",
   siid: 529
};
udc.setLocalTestData(connection);
// fetch some data...

Explanation:

Depending on the transferred connection type, data is requested from the corresponding source and then made available. For this, the following distinction is made:

• Testing against server web services, handover of DebugServer object

• Testing against player web services, handover of DebugClient object

• Testing against a local file, handover of DebugFile object

Further information can be found under Setting up a UDC test connection.

registerLogHandler

By means of this function, it is possible to request additional logs via the gfUdcConnector.

Parameters:

{callback} onLog: returns log messsag {string}

Explanation:

var udc = new GFUdcConnector();
udc.registerLogHandler(function(message)
{
   console.log(message);
});

Explanation:

The registerLogHandler function is assigned with a call-back function as a parameter which in case of an entry, is invoked via the gfUdcConnector. The log notification is rendered as a parameter.