API & Integration Guide

This guide should be used after a Push Channels Publisher Account has been created. Its purpose is to guide you through the necessary steps to have your widgets showing up correctly and pushing the correct content.

Step 1: Widget Generator

Add our widget generator code to the webpages that will contain widgets. You can get the generator by clicking on the "Get Widget Generator Code" button within Widget Management. The generator can be placed anywhere within the <HEAD> or <BODY> tags of your webpages and it must be placed on every webpage that will contain widgets.

Step 2: Widget Placement

After you have created your widget(s) within Widget Management, each widget gets a "Widget ID" (as seen in Widget Management). With the id, place your widget according to the following HTML attributes:

id (Required): Add "id" attributes to any HTML elements that represent where you want widgets to show up. Set these "id" attributes equal to the "Widget ID's" from earlier. There is currently no limit as to how many widgets can be placed on a single webpage, however, you can not place a widget more than once on a single webpage.
_pc_wdescr (Optional): Set this attribute on any HTML element(s) that you are using to display a description for a widget, so that if the widget doesn't show up for any reason (deactivated, subscriber limit reached, etc.) we will automatically hide the HTML element you put this attribute on. Set this attribute equal to the "Widget ID" for which it corresponds.
_pc_wno_items (Optional): For each HTML element that you add the id attribute to, also set this attribute equal to the value one (1) to indicate that there are no items to push on this webpage for this widget. If you do not set this attribute to the value one (1) or do not set the attribute at all, our system will assume this page will, at some point, contains items to push. Why do we have this attribute? This is so that we know whether or not to try pushing items (if any are available) on the webpage for which this widget is placed. Disregard this attribute if you are using the API to push items or if you are setting the _pc_wdynamic_url attribute below.
_pc_wdynamic_url (Optional): For each HTML element that you add the id attribute to, also set this attribute equal to a URL. You will ONLY need to set this attribute if the information you are pushing meets ALL THREE of the following requirements:
1. You are NOT using the API to push items.
2. The information being pushed is located at a different URL from where this widget is being placed.
3. The URL for where the information resides will dynamically change, based on the page the widget is placed. If the URL you set this attribute equal to NEVER changes, DO NOT use this attribute and instead, set those "static" URLs within Widget Management.
Example use-case for using _pc_wdynamic_url: If you place this widget on a search page, but want to use the RSS feed associated with the search results, setting this attribute equal to that RSS feed URL is appropriate, since the RSS feed URL is located somewhere else and it dynamically changes based on the search criteria. NOTE: You do not need to set the _pc_wno_items attribute (above) if setting this _pc_wdynamic_url attribute.

Widget Placement Examples

    			
    			
    			
    			
    			
    			
    			
    			
    			
    			
    			
    			
    			Below is the widget...

Step 3: Widget's Content

The final step is to decide how this widget's content will be pushed. For each widget, choose one of the following options:

RSS/Atom: This is the easiest of the 3 options. While adding or editing a widget, simply enter the RSS/Atom feed URLs for where the content is located under the "Webpage Monitoring Settings". It's as simple as that and you don't have to continue reading this guide. NOTE: You can combine this option and the "Attributes" option below to aggregate RSS and non-RSS information into one stream of information to push.
Attributes: Add a few HTML attributes to your already existing HTML content, in order to let our system understand which content you want pushed. Read below for further details on adding attributes.NOTE: You can combine this option and the "RSS" option above to aggregate RSS and non-RSS information into one stream of information to push.
API: In the case when you have non-public facing websites or would like a back end approach, we offer direct HTTP POST requests of the information you want pushed. Read below for further details on using our API to send us the content you want pushed.

Integrating with Attributes

Add the following attributes to your HTML tags, in order to tell our system which content item(s) belong to each widget:

_pc_wiwrap (Required): Add this attribute to the HTML element that wraps the item's content. The HTML element chosen should wrap the HTML elements in which the title, summary, content groups, and URL are defined. If you do not have an HTML element wrapping the item, just create one. Set this attribute equal to the "Widget ID" to which it corresponds from Step #2 above.
_pc_wiid (Required)/(Optional): Add this attribute to the same HTML element that contains the _pc_wiwrap attribute. Set this attribute equal to a value that uniquely identifies this item from any others for the widget in which it corresponds. This is what keeps track of which items the subscriber(s) have and have not seen, so be sure not to have duplicates. NOTE: You may skip using this attribute if each item has a unique URL and in that case, just make sure to use the _pc_wilink attribute below.
_pc_wilink (Required)/(Optional): Add this attribute to the same anchor HTML element (<A>) that contains the endpoint URL for this item. The endpoint URL must be within that element's "href" attribute. Set this attribute equal to the number one (1). If not used, the URL from which the subscriber signed up will be used. NOTE: URLs are automatically shortened via bit.ly for SMS messages.
_pc_wititle (Required): Add this attribute to the same HTML element that contains the title of this item. Set this attribute equal to the number one (1). For setting titles based on the channel, see the Channel specific attributes section below. NOTE: For SMS messages, the title is used as the first sentence of the message, followed by the _pc_wisumm content, with all content being cut-off after 100 characters (40 characters of the normal 140 character SMS message length are reserved for the shortened URL and HELP text).
_pc_wisumm (Optional): Add this attribute to the same HTML element that contains the summary of this item. Set this attribute equal to the number one (1). If not used, no summary for this item is sent to the subscriber. For setting summaries based on the channel, see the Channel specific attributes section below. NOTE: For SMS messages, the _pc_wititle is used as the first sentence of the message, followed by the summary content, with all content being cut-off after 100 characters (40 characters of the normal 140 character SMS message length are reserved for the shortened URL and HELP text). For email messages, the summary is used as the body content for the sent email.
_pc_wiimg (Optional): Add this attribute to the same HTML element that contains the thumbnail image for this item. Set this attribute equal to the number one (1). If not used, no thumbnail image for this item is sent to the subscriber. NOTE: Thumbnail images currently only display in messages sent through the email Channel. Also NOTE: Thumbnail images are not resized from their original sizes, so be sure to keep the sizes consistant.
Channel specific attributes - If you wish to have different content sent depending on the channel, use the following attributes:
- _pc_sms_wimessage (Optional): Only applies to the SMS channel. If used, this attribute takes precedence over the _pc_wititle and _pc_wisumm attributes for SMS, such that all three attributes can be used at the same time. HINT: If necessary, you can use CSS to hide the element to which you apply this attribute with the following CSS rule: "display:none;" (see the example to the right). NOTE: All content is automatically cut-off after 100 characters (40 characters of the normal 140 character SMS message length are reserved for the shortened URL and HELP text.)
- _pc_email_wititle (Optional): Same as _pc_wititle, but only applies to the Email channel. If used, this attribute takes precedence over the _pc_wititle attribute for Email, such that both attributes can be used at the same time. HINT: If necessary, you can use CSS to hide the element to which you apply this attribute with the following CSS rule: "display:none;" (see the example to the right).
- _pc_email_wibody (Optional): Same as _pc_wisumm, but only applies to the Email channel. If used, this attribute takes precedence over the _pc_wisumm attribute for Email, such that both attributes can be used at the same time. HINT: If necessary, you can use CSS to hide the element to which you apply this attribute with the following CSS rule: "display:none;" (see the example to the right). For email messages, the summary is used as the body content for the sent email.
- _pc_notifo_winotification_title (Optional): Same as _pc_wititle, but only applies to the Notifo desktop channel. If used, this attribute takes precedence over the _pc_wititle attribute for Notifo desktop notifications, such that both attributes can be used at the same time. HINT: If necessary, you can use CSS to hide the element to which you apply this attribute with the following CSS rule: "display:none;" (see the example to the right). NOTE: All HTML content is stripped and URLs are automatically shortened via bit.ly. [Character Limit: 180]
- _pc_notifo_winotification_msg (Optional): Same as _pc_wisumm, but only applies to the Notifo desktop channel. If used, this attribute takes precedence over the _pc_wisumm attribute for Notifo desktop notifications, such that both attributes can be used at the same time. HINT: If necessary, you can use CSS to hide the element to which you apply this attribute with the following CSS rule: "display:none;" (see the example to the right). For Notifo desktop notifications, this field is used as the message body for the sent notification. NOTE: All HTML content is stripped and URLs are automatically shortened via bit.ly. [Character Limit: 8000]
- _pc_notifo_wimessage (Optional): Only applies to the Notifo smart phone channel. If used, this attribute takes precedence over the _pc_wititle and _pc_wisumm attributes for Notifo smart phone messages, such that all three attributes can be used at the same time. HINT: If necessary, you can use CSS to hide the element to which you apply this attribute with the following CSS rule: "display:none;" (see the example to the right). NOTE: All HTML content is stripped and URLs are automatically shortened via bit.ly. [Character Limit: 750]
Content group attributes - Specify one or more of these attribute pairs in order to group your content:
- _pc_wicg_name & _pc_wicg_value (Required if defined while building your widget): Add these attributes to any HTML element or simply create a new HTML element (<SPAN> recommended). Both the _pc_wicg_name and _pc_wicg_value attributes must be applied on the same HTML element to take affect. Set the _pc_wicg_name attribute equal to a content group name you define while building your widget. Set the _pc_wicg_value attribute equal to a content group value you define while building your widget. Only one content group name and content group value can be specified per HTML element; therefore, to specify multiple content groups, use multiple HTML elements (see the example to the right).

Examples with Attributes

Simple item without any optional attributes

    	        
    	            some content 0
    	            a summary of information for some content 0

Specifying the title for all channels

    	        
    	            some content 1
    	            a summary of information for some content 1

Specifying the message for the SMS channel, but hiding it from view

    	        
    	            A title
    	            a summary of information
    	            All the SMS content goes here, with a maximum of 100 characters.

Specifying the message for the Notifo smart phone channel, but hiding it from view

    	        
    	            A title
    	            a summary of information
    	            All the Notifo smart phone content goes here.

Specifying the title, summary, and link

    	        
    	            some content 2
    	            a summary of information for some content 2

Specifying the title and summary for the Email channel, but hiding it from view

    	        
    	            A title
    	            a summary of information
    	            The Email title goes here
    	            The Email body goes here

Specifying the title and summary for the Notifo desktop channel, but hiding it from view

    	        
    	            A title
    	            a summary of information
    	            The Notifo desktop notification title goes here
    	            The Notifo desktop notification body content goes here

Specifying the title, summary, and link

    	        
    	            some content for $30.00
    	            a summary of the item with a cost of $30.00

Specifying a single content group name and multiple values

    	        
    	           
    	           
    	           
    	            some content 4
    	            a summary of information 5

Specifying multiple content group names and their values

    	        
    	           
    	           
    	            some content 5
    	            a summary of information 5

Specifying multiple content group names and multiple values

    	        
    	           
    	           
    	           
    	           
    	            some content 6
    	            a summary of information 6

Integrating with the API

Overview:
Using our push API is appropriate for those that want to push content that is located on non-public facing webpages (behind a username/password, for example) or if the content isn't rendered on a webpage. It is important to note that if you are placing a widget behind non-public facing webpages, you must set a variable within the "Widget Generator Code" (from Step 1). The UID variable is required, while the EMAIL and CELLPHONE variables are optional:

UID -- Set this variable to the urlencoded version of the internal user ID (max length of 255 characters) of the current user viewing the page with the widget on it. This allows our system to synchronize our subscriber ID with your user ID, so that you can push your content, specific to individual users (see _pc_wiuser_ids below). Setting this variable is only required if you choose to use the _pc_wiuser_ids API parameter below. Do not modify the default value of empty string ('') if you do not wish to use this variable. Also, don't forget to escape all single quotes (') within this variable.
EMAIL -- Set this variable to the internal email address of the current user viewing the page with the widget on it. This is only a convenience variable to auto-populate the email address form field in the widget, if the email channel is selected. Do not modify the default value of empty string ('') if you do not wish to use this variable. Also, don't forget to escape all single quotes (') within this variable.
CELLPHONE -- Set this variable to the internal cell phone number of the current user viewing the page with the widget on it. This is only a convenience variable to auto-populate the cell phone number form field in the widget, if the SMS channel is selected. Do not modify the default value of empty string ('') if you do not wish to use this variable. Also, don't forget to escape all single quotes (') within this variable.

Example of setting variables within the "Widget Generator Code"

                (function() {
                    var UID = 'THE_USER_ID_GOES_HERE'; //<-- The user id of the current user viewing the widget
                    var EMAIL = 'the_email_address@goes.here'; //<-- The email address of the current user viewing the widget
                    var CELLPHONE = '5555555555'; //<-- The cell phone number of the current user viewing the widget
                    var NOTIFO_PHONE_USERNAME = 'notifo_username'; //<-- The notifo username of the current user viewing the widget
                    var NOTIFO_COMP_USERNAME = 'notifo_username'; //<-- The notifo username of the current user viewing the widget
                    
                    //... 
                    
                })();

Request Parameters:
To use the API, you will send an HTTP POST request to http://www.pushchannels.com/app/api with the following POST request parameters:

ak (string): Your API Key. You can view your API Key by clicking on "API Authentication" from within Widget Management.
ap (string): Your API Password. You can view your API Password by clicking on "API Authentication" from within Widget Management.
debug (int): Setting this value to one (1) will allow you to test for any errors or warnings with your push without pushing any items. Once you know your API request is error/warning free, set this to zero (0) or just do not set it at all during your API call.
items (string): The content items to push as a JSON encoded array of associative arrays. Each content item can have the following fields set as the keys in the associative array:
- _pc_wiurl (Required) (string): The URL to the detail page of this content item.
- _pc_widigest_url (Required) (string): The URL to a page in which this content item is listed (should not be the detail page). This is normally a URL to the page in which this content item is listed along with other content items. This field designates what URL to send the subscriber to, in case there are too many results to send via the text message (SMS) channel. Currently, the maximum sent before sending the digest URL is 5.
- _pc_email_wititle (Required for the email channel) (string): The content item's title for the email channel. [Character Limit: 180]
- _pc_email_wibody (Optional) (string): The content item's body for the email channel. [Character Limit: 8000]
- _pc_sms_wimessage (Required for the sms channel) (string): The content item's message for the sms channel. [Character Limit: 140]
- _pc_notifo_winotification_title (Required for the Notifo desktop channel) (string): The content item's title for the Notifo desktop channel. [Character Limit: 180]
- _pc_notifo_winotification_msg (Optional) (string): The content item's body for the Notifo desktop channel. [Character Limit: 8000]
- _pc_notifo_wimessage (Required for the Notifo smart phone channel) (string): The content item's message for the Notifo smart phone channel. [Character Limit: 750]
- _pc_wids (Required) (string or array of strings): The widget ID(s) for which this content item belongs (as seen in Widget Management). Can be a single widget ID string or an array of string widget IDs.
- _pc_wiuser_ids (Optional) (int/string or array of ints/strings): The user ID(s) for which this conent item can be pushed. Can be a single user ID integer/string or an array of integer/string user IDs. This parameter is only applicable if you follow the directions above regarding synchronizing your user IDs with our subscriber IDs.
- _pc_wiid (Optional) (string): If your content items don't have unique _pc_wiurl values, supply this as the content item's unique ID, in order to distinguish it from any other content items you have or will be pushing.
- _pc_wiimg_src (Optional) (string): The URL to this content item's thumbnail image. Only applies to the email channel.
- _pc_wicgs (Optional) (associative array of arrays): If you have defined content groups for this widget, the content group names and values for which this content item belongs should be specified here. (Example: Array('a content group name' => Array('a value 1', 'a value 2'), 'a second content group name' => Array('a value 1'))

Example API Call with PHP and cURL

                // Create a curl handle and set some basic options
                $ch = curl_init();
                curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
                curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
                curl_setopt($ch, CURLOPT_POST, true);
                
                //Setup our API Key and API Password to send
                $curl_data['ak'] = '[API Key goes here]';
                $curl_data['ap'] = '[API Password goes here]';
                
                //Set debug to true to make sure we don't get any errors or warnings for this push.
                //This should be commented out or set to zero (0) for real pushes.
                $curl_data['debug'] = 1;
                
                //Now create our items package to send...
                
                //First item will be sent out to SMS subscribers
                $curl_data['items'][] = array(
                    '_pc_wiurl' => 'http://www.pushchannels.com/112', 
                    '_pc_sms_wimessage' => 'The SMS message to push', //<--Only applies to SMS channel
                    '_pc_wids' => array(
                        '_pc_wid_1', '_pc_wid_27'
                    ), 
                    '_pc_widigest_url' => 
                    'http://www.pushchannels.com/1'
                );
                
                //Second item will be sent out to email subscribers
                $curl_data['items'][] = array(
                    '_pc_wiurl' => 'http://www.pushchannels.com/213', 
                    '_pc_email_wititle' => 'The title to show in the email', //<--Only applies to email channel
                    '_pc_email_wibody' => 'The body to show in the email', //<--Only applies to email channel
                    '_pc_wids' => array(
                        '_pc_wid_1', '_pc_wid_27'
                    ), 
                    '_pc_widigest_url' => 'http://www.pushchannels.com/2'
                );
                
                //Third item will be sent out to SMS and email subscribers
                $curl_data['items'][] = array(
                    '_pc_wiurl' => 'http://www.pushchannels.com/31', 
                    '_pc_sms_wimessage' => 'The SMS message to push', //<--Only applies to SMS channel
                    '_pc_email_wititle' => 'The title to show in the email', //<--Only applies to email channel
                    '_pc_email_wibody' => 'The body to show in the email', //<--Only applies to email channel
                    '_pc_wids' => array(
                        '_pc_wid_1', '_pc_wid_27'
                    ), 
                    '_pc_widigest_url' => 'http://www.pushchannels.com/3'
                );
                
                //Fourth item will be sent out to Notifo desktop, Notifo smart phone, and email subscribers
                $curl_data['items'][] = array(
                    '_pc_wiurl' => 'http://www.pushchannels.com/31', 
                    '_pc_notifo_wimessage' => 'The Notifo smart phone message to push', //<--Only applies to Notifo smart phone channel
                    '_pc_notifo_winotification_title' => 'The title to show in the Notifo desktop notification', //<--Only applies to Notifo desktop channel
                    '_pc_notifo_winotification_msg' => 'The body to show in the Notifo desktop notification', //<--Only applies to  Notifo desktop channel
                    '_pc_email_wititle' => 'The title to show in the email', //<--Only applies to email channel
                    '_pc_email_wibody' => 'The body to show in the email', //<--Only applies to email channel
                    '_pc_wids' => array(
                        '_pc_wid_1', '_pc_wid_27'
                    ), 
                    '_pc_widigest_url' => 'http://www.pushchannels.com/3'
                );
                
                //Fourth item will be sent out to email subscribers, with the item containing a thumbnail image and 
                //will provide content groups the subscriber can filter by, as well as will only get sent to
                //the user with user ID 3
                $curl_data['items'][] = array(
                    '_pc_wiurl' => 'http://www.pushchannels.com/7576',
                    '_pc_email_wititle' => 'Title for the item',  //<-- Only applies to email channel
                    '_pc_wids' => '_pc_wid_26',  //<-- Shows that doesn't need to be an array if only pushing for one widget
                    '_pc_wiimg_src' => 'http://www.pushchannels.com/path_to_an_image.png',  //<-- Only applies to email channel
                    '_pc_email_wibody' => 'Body for the item',  //<-- Only applies to email channel
                    '_pc_widigest_url' => 'http://www.pushchannels.com/253',
                    '_pc_wicgs' => array(
                        /*The name of the first content group*/'content group #1' => array(
                            /*The values for the content group*/'a val', 'another val'
                        ),
                        /*The name of the second content group*/'content group #2' => array(
                            /*The values for the content group*/'a value for content group #2', 'another'
                        )
                    ), 
                    '_pc_wiuser_ids' => 3 //<-- Can also be an array of user IDs
                );
                
                //Now that we have our parameters setup, let's convert them into POST-safe parameters for cURL...
                $o = '';
                foreach ($curl_data as $k=>$v)
                {
                    if (!is_scalar($v))
                    {
                        $v = json_encode($v);
                    }
                    $o.= "$k=".utf8_encode(urlencode($v))."&";
                }
                $curl_data = substr($o, 0, -1);
                
                //Set our curl data to POST, along with the API endpoint URL
                curl_setopt($ch, CURLOPT_POSTFIELDS, $curl_data);
                curl_setopt($ch, CURLOPT_URL, 'http://www.pushchannels.com/app/api');
                
                //Execute the API call and place the response in $data
                $data = curl_exec($ch);
                
                //If an error didn't occur, print out the results
                if(!curl_errno($ch))
                {
                    echo '';
                    print_r(json_decode($data, true)); //<-- JSON decoded response
                    echo '';
                    die('');
                }
                else
                {
                    die('cURL error: '.curl_error($ch));
                }
                
                // Close handle
                curl_close($ch);

Response:
Any API call will return a JSON encoded string response with the following properties:

success (int): One (1) on a successful API call or zero (0) if any errors occured. Keep in mind, a success of one (1) will still be sent back, even with warnings.
num_new_items_pushed (associative array): An associative array of the number of new items pushed from your request. The keys of the associative array correspond to your widget ID(s) involved in the push. The values of the associative array correspond to how many new items were pushed.
error_code (int): If an error occurred, this will be a non-zero (0) value. Here are the error codes and their meanings:
- 100: Incorrectly formated API call. See the error_message propety returned for more information.
- 101: Incorrect Authentication. See the error_message propety returned for more information.
- 102: Empty push result, because no items were available to push. See the error_message propety returned for more information, as well as the warnings property.
error_message (string): The detailed error message corresponding to the error_code property returned.
warnings (array of strings): An array of string warnings that will correspond to any issues found with your request. For example, if one of your widgets in your push request are not active, the widgets will be skipped and a warning of these skips will be set in this array.