Search
Clear search
Close search
Google apps
Main menu

Channel Connect

Channel Connect is an HTML5 custom element that connects two creatives. The most common use is to connect a creative on a desktop with a creative on a mobile device. Channel Connect uses the Polymer library's implementation of custom elements.

Use Channel Connect to create a two-way connection between platforms. Connect a desktop creative with a mobile creative, then use the mobile device to control a desktop game. Or, connect two mobile creatives and create a two player game.

Features

  • One-way or two-way communication from a creative in a web browser to a mobile device.
  • A few ways to use Channel Connect:
    • Use a mobile device to swipe a web page and show a hidden section of an ad.
    • Use a mobile device as a TV remote, to switch between different videos in the creative.
    • Use a mobile device as a game controller for a creative in a web browser.
    • Use a mobile device to draw on or move elements around the page.
    • Send deals, dates, or locations to a mobile device.

Prerequisites

Includes

Before you can use the custom element, you need to add these scripts in the head of your creative's HTML file:

<script src="https://s0.2mdn.net/ads/studio/Enabler.js"></script>
<script src="https://www.gstatic.com/external_hosted/polymer/custom.elements.min.js"></script>
<script src="https://www.gstatic.com/ads/ci/channelconnect/2/channelconnect_min.js"></script> 

Set up the custom element

Add the custom element to your HTML file using the <ci-channelconnect-service> element.

Example Channel Connect tags
<ci-channelconnect-service
    mobileurl="http://example.com/mobile.html"
    secretkey="abcde12345">
</ci-channelconnect-service>
<ci-channelconnect-button>
  <div id="custom-content">
    <button><img src="click_to_play.png" alt="click to play"></button>
  </div>
</ci-channelconnect-button>
 

Set custom element attributes

Use attributes to set the key needed to access the Channel Connect server and the mobile creative URL. These attributes work the same way as standard HTML tags.

secretkey

Set the secret key needed to access the Channel Connect service. If you don't have a key, request one from your DoubleClick contact. While testing, set the secret key to an empty string (secretkey=""). This allows limited daily connection quotas from a limited set of testing domains. But don't forget to add a real key before the creative goes live.

Example

Set the secret key to xyz5678:

<ci-channelconnect-service
    mobileurl="http://example.com/mobile.html"
    secretkey="xyz5678">
</ci-channelconnect-service>
<ci-channelconnect-button>
  <div id="custom-content">
    <button><img src="click_to_play.png" alt="click to play"></button>
  </div>
</ci-channelconnect-button>
mobileurl

The URL of the mobile creative. The function requestShortMobileUrl returns a shortened version of this URL to make it quicker to type on a mobile device.

Example

Set the mobile creative URL to examplepetstore.com/mobile-game.html:

<ci-channelconnect-service
    mobileurl="examplepetstore.com/mobile-game.html"
    secretkey="abcde12345">
</ci-channelconnect-service>
<ci-channelconnect-button>
  <div id="custom-content">
    <button><img src="click_to_play.png" alt="click to play"></button>
  </div>
</ci-Service
connect-button>

Manage connections and send messages using API methods

Use the methods below to open and close connections and send messages back and forth between the two creatives.

ci.channelconnect.Service.getInstance()
Returns a singleton instance of the Channel Connect service manager.

Get a reference to the Channel Connect service manager
The Channel Connect service uses a singleton class to manage incoming server connections. Before you can call any of the methods below, you first need to get an instance of the class to call the methods with.

 

Example
var channelService = ci.channelconnect.Service.getInstance();
console.log(channelService.getAttribute('secretkey'));
connect()
Re-connects to the service. After the connection is established, the component dispatches the event ci.channelconnect.Service.EventType.OPEN
This method cannot be used to connect to the service the first time. A user must click on the <ci-channelconnect-button> element to establish the first connection. After the first connection is established, the connect() method can be used to re-open a connection without clicking the button.
Example
serviceInstance.connect(); 
connectMobile()
Connects the mobile creative to the mobile channel. Use only in the mobile asset. After the connection is established, the component dispatches the event ci.channelconnect.Service.EventType.OPEN.
Example
var openHandler = function() {
  console.log('Connection open');
};
serviceInstance.addEventListener(ci.channelconnect.Service.EventType.OPEN, 
    openHandler);
serviceInstance.connectMobile();
close()
Closes the connection to the channel service. After the connection is closed, the component dispatches the event ci.channelconnect.Service.EventType.CLOSE.
Example
var closeHandler = function() {
  console.log('Connection closed');
};
serviceInstance.addEventListener(ci.channelconnect.Service.EventType.CLOSE,
    closeHandler);
serviceInstance.close();
dispose()
Clean up the component when it should no longer be used. If the component needs to be reused after dispose is called, a new instance must be created.
Example
// Clean up the component to free up its resources.
serviceInstance.dispose();
getSessionId()
Returns the current session ID. Each communication channel between two connected devices has a unique session ID. Add the session ID as a URL parameter for the mobile asset URL to share a reference to the channel.
Example
var sessionId = serviceInstance.getSessionId();
window.open('http://www.foo.com/mobile.html?id=' + sessionId);
isServiceConnected()
Returns whether the component is connected to the service.
Example
if (serviceInstance.isServiceConnected()) {
  console.log('Connected');
} else {
  console.warn('Not Connected');
}
requestShortMobileUrl(opt_mobileUrl)

Returns the shortened mobile URL.

Parameter:

  • opt_mobileUrl: Optional URL. If used, this value will override the mobileurl attribute.
Example
var shortUrlHandler = function(event) {
  console.log('Shortened url:', event.detail.id)l
};
serviceInstance.addEventListener(ci.channelconnect.Service.EventType.SHORT_MOBILE_URL, 
    shortUrlHandler);
var mobileUrl = 'http://foo.com/mobile.html';
serviceInstance.requestShortMobileUrl(mobileUrl);
sendMessage(message)

Sends a message to the connected companion.

Parameter:

  • message: The message to send. Messages must be of the type ci.channelconnect.ChannelMessage.
Example
var message = new ci.channelconnect.ChannelMessage({
  message: 'HTML5 rocks!',
  name: 'DoubleClick',
  randomNumber: Math.random()
});
serviceInstance.sendMessge(message); 

Events

The Channel Connect element dispatches the following events:

  • ci.channelconnect.Service.EventType.OPEN
    Dispatched when the connection to the channel has been successfully established. You must listen for this event before you can open the mobile client and let it connect to the available channel.
  • ci.channelconnect.Service.EventType.MESSAGE
    Dispatched when a message from the connected companion client is received. The event object includes the following property:
    • data: Message object.
  • ci.channelconnect.Service.EventType.CLOSE
    Dispatched when the connection to the backend service is closed.
  • ci.channelconnect.Service.EventType.ERROR
    Dispatched when a backend error occurs.
  • ci.channelconnect.Service.EventType.SHORT_MOBILE_URL
    Dispatched when the short mobile url has been generated. The event object has the following property:
    • id: The short url

Code examples

Example with both HTML and JavaScript

HTML tag

<ci-channelconnect-service id="service"
    secretkey="abcde12345"
    mobileurl="http://foo.com/mobile.html">
</ci-channelconnect-service>

JavaScript

var service = document.getElementById('service');
var shortUrlHandler = function(event) {
  console.log('Shortened url:', event.detail.id);
};

service.addEventListener(ci.channelconnect.Service.EventType.OPEN, 
    function() {
  console.log('Connection open');
  serviceInstance.addEventListener(ci.channelconnect.Service.EventType.SHORT_MOBILE_URL, 
      shortUrlHandler);
  var mobileUrl = 'http://foo.com/mobile.html';
  serviceInstance.requestShortMobileUrl(mobileUrl);
});
  
service.addEventListener(ci.channelconnect.Service.EventType.MESSAGE,
    function(event) {
  var jsonString = event.detail.toString().replace('\\n', '');
  var jsonObject = JSON.parse(jsonString);
  console.log('Message: ', jsonObject);
});

Example using only JavaScript

As an alternative to the HTML and JavaScript example above, you can create the element dynamically using only JavaScript:


var service = document.createElement('ci-channelconnect-service');
service.setAttribute('secretkey', 'abcde12345')
service.setAttribute('mobileurl', 'http://foo.com/mobile.html')
service.addEventListener(ci.channelconnect.Service.EventType.OPEN,
    function() {
  console.log('Connection open');
  serviceInstance.addEventListener(ci.channelconnect.Service.EventType.SHORT_MOBILE_URL, 
      shortUrlHandler);
  var mobileUrl = 'http://foo.com/mobile.html';
  serviceInstance.requestShortMobileUrl(mobileUrl);
});
  
service.addEventListener(ci.channelconnect.Service.EventType.MESSAGE,
    function(event) {
  var jsonString = event.detail.toString().replace('\\n', '');
  var jsonObject = JSON.parse(jsonString);
  console.log('Message: ', jsonObject);
});

Preview and testing

The component cannot be tested from your local file system. Instead, test from a local web server. To create a simple web server for testing:

  1. Open a terminal window and enter the following commands:
    cd my_folder
    python -m SimpleHTTPServer 8080
    Replace my_folder with the path to the folder where your creative files are on your computer.
  2. Open the creative from the URL: http://localhost:8080/creative.html.

To test the mobile asset on a mobile device, upload the mobile assets to Asset Library and get the full static URL using folder base paths

Hosting mobile assets

  1. Upload your mobile creative assets to Asset Library.
  2. Get the full static URL to your HTML file. Get a static URL using Asset Library's folder base paths
Was this article helpful?
How can we improve it?