PHP Developers

On this page, you will find the steps required to download, install and test Broadsign Control API for a PHP integration.

Note: Our Broadsign Control API documentation for SOAP integrations describes procedures for Ubuntu Linux operating systems. However, a Windows version of the SDK is available. Where suitable, we make note of special requirements for Windows users.

Note: For more detailed information about Broadsign Control API's protocols, operations, libraries and WSDL files, see Implementation.

As a PHP developer, to integrate with Broadsign Control API, you need to download and install the SDK. Also, you will need to install the PHP command line interpreter.

Supported Ubuntu Versions

Broadsign Control's SOAP SDK is compatible with the following 64-bit Ubuntu versions:

Supported Linux Versions

  • Ubuntu Desktop 22.04 LTS (Minimum Install)
  • Ubuntu Desktop 20.04 LTS (Minimum Install)
  • Ubuntu Desktop 18.04 LTS (Minimum Install)

Tip: See Ubuntu Release Cycle for official supported Ubuntu versions.

Ubuntu 22.04 Hardware Acceleration Differences

With the support of Ubuntu 22, the Broadsign Control hardware acceleration performance undergoes notable changes compared to Ubuntu 20 and earlier versions. The key differences are as follows:

  1. Supported Hardware:
    • Hardware acceleration is now supported on Comet/Ice/Amber Lake (NUC10) and subsequent models in Ubuntu 22. This is a significant enhancement compared to Ubuntu 20 and earlier versions.
  2. Performance Issues on Ubuntu 22:
    • Using hardware acceleration with 60 FPS video on older hardware, such as Comet/Ice/Amber Lake (NUC10) and earlier, may result in performance issues. Broadsign recommends to either disable hardware acceleration or opt for 30 FPS video playback.
    • On Kaby/Appollo Lake (NUC7) and earlier, Broadsign recommends to set the environment variable LIBVA_DRIVER_NAME=i965, which will force Broadsign Control Player to use the Intel i965 driver.
    • For Coffee/Amber/Whiskey Lake (NUC7) and earlier, hardware acceleration is not functional for H265/HEVC video with high-depth color profiles, such as 10bit/channel 422.

The hardware acceleration issues mentioned above do not apply when hardware acceleration is disabled in the player's configuration, which is the default setting.

To download and install the Broadsign Control API SDK:

Below, we provide instructions for Ubuntu Linux users:

  1. From the portal, download the Broadsign Control API SDK.
    • You can download versions of Broadsign Control API compatible with either Windows or Ubuntu Linux.
    • To access earlier versions of the SDK, select Previous Releases.

  2. Install Broadsign Control API.

    Copy 
    sudo dpkg -i bssdk-13_0_0-xxx-i386.deb

  3. Install the PHP command-line interpreter.

    Copy 
    sudo apt-get install php-soap
    sudo apt-get install php-cli

    4. Note: If you are working on Ubuntu Linux 16.04, you will need to install php-mbstring:

    Copy 
    sudo apt-get install php-mbstring

Note: If you are installing PHP on Windows, you will need some extra configuration to get HTTPS support; otherwise, you will receive this error message: "SSL support is not available in this build". This is a well-known problem (solution).

When integrating with Broadsign Control API in production, we recommend a cryptographic certificate and key.

You must install them on the client machine that is associated with a user — with proper privileges — in Broadsign Control Administrator. For auditing and security reasons, it is best to create a new user solely for use with Broadsign Control API. Simply add a new user through Broadsign Control Administrator, choose an arbitrary password and assign the proper privileges.

Then, you must generate a private key and submit a Certificate Signing Request (CSR) to Broadsign. Broadsign will respond with a signed certificate and a public key fingerprint:

  • The signed certificate and your private key are your authentication tokens.
  • The public key fingerprint is assigned to the user you created, thereby allowing Broadsign Server to authenticate the user and assign the correct security context.

To authenticate your Broadsign Control API user:

  1. Create the private key:

    Copy 
    openssl genrsa -out sdk_key.pem 2048

  2. Create the Broadsign Certificate Signing Request (CSR):

    Copy 
    openssl req -new -key sdk_key.pem -out sdk_req.pem
    • Fill out the fields accurately.
    • DO NOT specify any of the following extra attributes:
      • a challenge password
      • an optional company name

  3. Send the Certificate Signing Request (CSR) to Broadsign. Include the following information:

    • To: services@broadsign.com
    • Subject: SDK CSR
    • Attachment: [sdk_req.pem]

    • Body: Please find attached the API Certificate Signing Request for [your company's name].

      Warning: Do not send your private key. Keep it secure at all times. Anyone with access to your private key could make unapproved changes to your domain.

      Note: If the email address from which you send the request is unregistered at Broadsign Community, you will receive a bounce-back email. You will need to have a registered contact from your organization contact us to register the email.

  4. Receive the signed certificate and the public key fingerprint from Broadsign.
  5. Assign the public key fingerprint to your designated Broadsign Control API user:
    1. In Broadsign Control Administrator, from the resource tabs on the left, select Users.
    2. Find and double-click your Broadsign Control API user.
    3. In the User Properties, go to the Credentials tab.

    4. In the Public Key Fingerprint section, paste your fingerprint.

      • The user making the requests must have a valid fingerprint value that matches the certificate being used on the client side of the mutually-authenticated SSL connection.
      • The fingerprint is a series of hexadecimal characters, 20 pairs separated by colons.

The local certificate allows Broadsign Server to authenticate you.

When sending requests to Broadsign Control API, the request needs a merged key and certificate file. Concatenate both your private key and the signed certificate provided by Broadsign Services.

To create your local certificate:

  1. Put the sdk_key.pem and sdk_cert.pem files into the same folder.
  2. Using the terminal, browse to the directory.

  3. Execute the command below:

    Copy 
    cat sdk_key.pem sdk_cert.pem > merged_cert.pem

For Windows users:

  1. Using your text editor, create a new file named merged_cert.pem.
  2. Append the content of sdk_key.pem and sdk_cert.pem, in that order.

The final file should resemble the image below.

Note: This is a false certificate. Do not copy.

Broadsign Control API ships with a library of helper classes, functions, and configurations called soaplib.php.

To configure your installation:

  1. In the global variables of your soaplib.php file, specify the location of your newly created merged_cert.pem.

  2. Point the host_variable to the sandbox.

    For more information about using the sandbox, see About the Sandbox (SOAP).

Configuration

Broadsign Control API ships with a Library of helper configurations, classes and functions called soaplib.php (see Configuration Section and Classes and Functions, below).

Configuration Section

Copy
/* Global Configuration Section */
global $sdk_root, $ca_cert, $local_cert, $bss_host, $api_root;
$bss_host = 'https://bssopen-sandbox.broadsign.com:10803';
$sdk_root = '/opt/broadsign/suite/sdk';
$api_root = $sdk_root . '/api';
$ca_cert = $sdk_root . '/certs/ca_cert.pem';
$local_cert = '/home/jon/certs/merged_cert.pem';
$print_requests= 1;
        $print_responses = 1;

 

ElementDescription
bss_hostThis is the hostname to connect to. Broadsign Server only accepts SOAP connections on port 10803. Along with your SDK access, you were provided with a sandbox server on which to test and develop your application. Once your application is ready to be deployed to production, this hostname should change to: https://bssopen.broadsign.com:10803.
sdk_rootThis is the SDK root installation path, which defaults to /opt/broadsign/suite/sdk.
api_rootThis is the path to the WSDL files used by soaplib.
ca_certThis is the path to the certificate used to authenticate the identity of the server. It is included in the SDK.
local_certThis is the path to your local certificate that will allow Broadsign Server to authenticate you. soaplib requires a merged key and certificate file. Concatenate both your private key and the signed cert provided by Broadsign Services: cat sdk_key.pem sdk_cert.pem > merged_cert.pem
print_requestsThis is a debugging tool that will print to stdout all the XML requests sent to the server. To disable the printing of requests, set print_requests to “0”.
print_responsesThis is a debugging tool that will print to stdout all the XML responses received from the server. To disable the printing of responses, set print_responses to “0”.

Classes and Functions

The soaplib.php library is not intended to be a comprehensive implementation that meets all possible client application needs. Rather, it is a collection of base classes and functions that show how to perform the internal processing needed to send requests and handle responses.

More complex operations will most likely need extra methods and parameters according to the application’s needs. For example, if you need to perform a list operation with a not_modified_since value that is not epoch, these functions would need to be modified.

Here is a quick overview of the classes and functions provided:

Class/FunctionDescription
SoapAdapterThis class inherits from the native PHP SoapClient and automatically handles the conversion to and from UTF-8 and UTF-16.
CreateOperationThis function creates a SoapAdapter instance by setting the mutual authentication properties of the SSL context and constructing the path to the WSDL file.
CreateSimpleRequestThis function builds the body of a simple request.
PerformSimpleOperationThis function ties it all together by creating an operation and a request, performing the operation and returning the response object.

If you have resources on your domain, a simple test is to call criteria_mgr_list to output all of your criteria.

To test your installation:

  1. Execute the following command:

    Copy 
    sudo /opt/broadsign/suite/sdk/samples/php/criteria_mgr_list --domain=44862

  2. Include the following request:

    Copy 
    <?xml version="1.0" encoding="UTF-8"?>
    <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://www.broadsign.com/wsdl_ops">
        <SOAP-ENV:Body>
            <ns1:request not_modified_since="1970-01-01T00:00:00" token="0" requestid="1" version="7" name="criteria_mgr_list">
                <criteria domain_id="44862"/>
            </ns1:request>
        </SOAP-ENV:Body>
    </SOAP-ENV:Envelope>

    Your response should look something like this:

    Copy 
    <?xml version="1.0" encoding="utf-16"?>
        <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:wsdl_ops="http://www.broadsign.com/wsdl_ops" xmlns="http://www.broadsign.com/wsdl_ops">
            <soap:Body>
                <wsdl_ops:response name="criteria_mgr_list" version="7" resource_type="criteria" not_modified_since="2016-05-06T15:48:46Z" op_type="list" status="complete" requestid="1" ns="user">
                    <criteria name="Hawaii" container_id="641556" domain_id="44862" type="0" attributes="" active="0" id="643409"/>
                    <criteria name="Publix" container_id="1770875" domain_id="44862" type="0" attributes="" active="0" id="647311"/>
                    <criteria name="Honolulu, HI - 071" container_id="329096" domain_id="44862" type="0" attributes="" active="0" id="672225"/>
                    <criteria name="PCV_3503901" container_id="11273416" domain_id="44862" type="0" attributes="" active="1" id="11273417"/>
                    <criteria name="Mauro's TV" container_id="1770875" domain_id="44862" type="0" attributes="" active="0" id="85934699"/>
                    [...]
                    [...]

Once you have tested your installation, you could do one of the following:

  • Test the Sandbox – Broadsign provides developers with a sandbox as a learning environment and to test applications. See About the Sandbox (SOAP).
  • Record Requests to File – You can record to file all requests made from Broadsign Control Administrator and Broadsign Control Player to Broadsign Server. This valuable tool helps developers debug their code and become familiar with Broadsign Control API. See Recording Requests to File (SOAP).
  • Explore Common Use Cases – We provide background information and code samples for a number of common use cases. See Use Cases (SOAP).
  • Explore Broadsign Control Administrator and Broadsign Control Player – We encourage developers integrating with Broadsign Control API to explore our resources in the context of our other products. We created a number of video and online tutorials that provide a foundation in Broadsign Control Administrator and Broadsign Control Player. See Quick Start Tutorial and Training Videos.