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 appropriate, 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.
Note: Starting from Broadsign Control Player version 13.2, we are deprecating support for both 32-bit and 64-bit edition of Ubuntu 14.04.
Broadsign Control's SOAP SDK is compatible with the following 32-bit Ubuntu versions:
- Ubuntu Desktop 14.04 LTS
Broadsign Control's SOAP SDK is compatible with the following 64-bit Ubuntu versions:
- Ubuntu Desktop 18.04 LTS
- Ubuntu Desktop 16.04 LTS
- Ubuntu Desktop 14.04 LTS
Below, we provide instructions for Ubuntu Linux users:
- 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.
Install Broadsign Control API.
sudo dpkg -i bssdk-13_0_0-xxx-i386.deb
Install the PHP command-line interpreter.
sudo apt-get install php-soap
sudo apt-get install php-cli
Note: If you are working on Ubuntu 12, you will need the following command-line interpreter package (instead of the one mentioned above):
sudo apt-get install php5-cli
Note: If you are working on Ubuntu Linux 16.04, you will need to install php-mbstring:
sudo apt-get install php-mbstring
Note: If you are installing PHP on Windows, you will need some additional 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 appropriate 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 appropriate 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.
Create the private key:
openssl genrsa -out sdk_key.pem 2048
Create the Broadsign Certificate Signing Request (CSR):
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
Send the Certificate Signing Request (CSR) to Broadsign. Include the following information:
- To: email@example.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, you will receive a bounce-back email. You will need to have a registered contact from your organization contact us to register the email.
- Receive the signed certificate and the public key fingerprint from Broadsign.
- Assign the public key fingerprint to your designated Broadsign Control API user:
- In Broadsign Control Administrator, from the resource tabs on the left, select Users.
- Find and double-click your Broadsign Control API user.
- In the User Properties, go to the Credentials tab.
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.
- Put the sdk_key.pem and sdk_cert.pem files into the same folder.
- Using the terminal, browse to the directory.
Execute the command below:
cat sdk_key.pem sdk_cert.pem > merged_cert.pem
For Windows users:
- Using your text editor, create a new file named merged_cert.pem.
- 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:
- In the global variables of your soaplib.php file, specify the location of your newly created merged_cert.pem.
Point the host_variable to the sandbox.
For more information about using the sandbox, see About the Sandbox (SOAP).
ConfigurationBroadsign Control API ships with a Library of helper configurations, classes and functions called soaplib.php (see Configuration and Classes and Functions, below).
/* 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;
|bss_host||This 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_root||This is the SDK root installation path, which defaults to /opt/broadsign/suite/sdk.|
|api_root||This is the path to the WSDL files used by soaplib.|
|ca_cert||This is the path to the certificate used to authenticate the identity of the server. It is included in the SDK.|
|local_cert||This 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_requests||This 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_responses||This 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”.|
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 demonstrate how to perform the internal processing needed to send requests and handle responses.
More complex operations will most likely need additional 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:
|SoapAdapter||This class inherits from the native PHP SoapClient and automatically handles the conversion to and from UTF-8 and UTF-16.|
|CreateOperation||This function creates a SoapAdapter instance by setting the mutual authentication properties of the SSL context and constructing the path to the WSDL file.|
|CreateSimpleRequest||This function builds the body of a simple request.|
|PerformSimpleOperation||This 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:
Execute the following command:
sudo /opt/broadsign/suite/sdk/samples/php/criteria_mgr_list --domain=44862
Include the following request:
<?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:
<?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.