About the Button

We have created an API that will allow developers to add a "Deploy through SiteApps" button on their site so their app can be installed on SiteApps with configured parameters.

We believe this can be beneficial do developers for a couple of reasons:

• Developers can allow a streamlined sign-up and deploy process from within their interface/site;
• Developers can help configure advanced configurations for potential sites and clients.

A good example is an app that needs some sort of frequency control or directed for a specific segment.

The Code

Below we will go through how to create a deploy button for your app in your interface.  We will be using the Image Switcher app as an example.

  Mandatory Parameters

Necessary code for every deploy.

<link type="text/css" href="http://siteapps.com/css/sa_window.css" rel="stylesheet"/>
<script type="text/javascript" src="http://siteapps.com/js/sa_window.js"></script>
<form method="post" action="https://siteapps.com/api/deploy" target="sa_win_deploy">

 What 

The app that will be deployed - use the complete URL of the app on the SiteApps Marketplace.  

<input type="hidden" name="app_id" value="http://siteapps.com/app/image_switcher-22"/>

Now we have to submit the actual App Parameters.  The parameters are listed based on the order presented in the marketplace.  Each app has different parameters numbers and configuration.

<input type="hidden" name="param_1" value="Value you want for Parameter 1"/>
<input type="hidden" name="param_2" value="Value you want for Parameter 2"/>
<input type="hidden" name="param_3" value="Value you want for Parameter 3"/>

 When 

Then input the default "when" parameters (no filters), show below.  If you do wish to use time and date filters, check the optional parameters section below.

<input type="hidden" name="when_always" value="1"/>

Lastly, simply finish by inputting the submit button and the closing the form.

<input type="button" id="sa_deploy_button" value="Deploy this app" onclick="sa_post(this)"/>
</form>

  Optional Parameters

You can set other configurations you would like for a specific deploy.

 When

Select time date and time configurations for when your app will be deployed on the site.  If you do wish to use filter, change the "value" of the "when_always" option to 0:

<input type="hidden" name="when_always" value="0"/>

<input type="hidden" name="when_timezone" value="-03:00"/>

<input type="hidden" name="when_start_date" value="2011-04-01 08:00"/>
<input type="hidden" name="when_end_date" value="2011-04-08 23:00"/>

<input type="hidden" name="when_days_of_week" value="1,2,3,4,5"/>
<input type="hidden" name="when_time_of_day" value="12,13,14,15,16,17"/>

 Who 

You can define what segments this app will be valid for or which you would like to exclude.  Currently, SiteApps supports 5 segments, all listed below.  In case you want the app to be deployed to all users, simply do not include any of the options below. 

Select the segments you want the app to be deployed to:

<input type="hidden" name="who_include_1" value="New Visitor"/>
<input type="hidden" name="who_include_2" value="Search"/>
<input type="hidden" name="who_include_3" value="iPad"/>
<input type="hidden" name="who_include_4" value="Returning Visitor"/>
<input type="hidden" name="who_include_5" value="Social Media"/>

Now, select the segments you DO NOT want the app to be deployed to:

<input type="hidden" name="who_exclude_1" value="New Visitor"/>
<input type="hidden" name="who_exclude_2" value="Search"/>
<input type="hidden" name="who_exclude_3" value="iPad"/>
<input type="hidden" name="who_exclude_4" value="Returning Visitor"/>
<input type="hidden" name="who_exclude_5" value="Social Media"/>

You can also use some of Google's Analytics data for segmentation.  To use this please include this parameter:

<input type="hidden" name="who_ga_integration" value="1"/>

Then specify the data you want to segment, like the examples below:

<input type="hidden" name="who_traffic_source" value="bing"/>
<input type="hidden" name="who_traffic_medium" value="organic"/>
<input type="hidden" name="who_keyword_term" value="search_term"/>
<input type="hidden" name="who_ad_content" value="xmas_ad"/>
<input type="hidden" name="who_campaign_name" value="campaignx"/>

 Where

To define where on the website you want the app deployed you can either select to use the site's homepage or limit URLs.  If you do none of the above, the app will be deployed on the entire site.

In case you want the app to be deployed only on the home page, use the following parameter:

<input type="hidden" name="where_only_homepage" value="1"/> 

To limit URLs, you can add the entire URL or use regular expressions below.  A maximum of 5 URL expressions can be used for inclusion and exclusion.

To include URLs:

<input type="hidden" name="where_include_1" value="/news/"/>
<input type="hidden" name="where_include_2" value="/articles/"/>

To exclude URLs:

<input type="hidden" name="where_exclude_1" value="/support"/>
<input type="hidden" name="where_exclude_2" value="/wiki"/>

 How

You can also set frequency control for the deploy.  Below are the three types of frequency controls you can use, even interchangeably. 

<input type="hidden" name="how_max_visit" value="0"/>
<input type="hidden" name="how_max_visitor" value="0"/>
<input type="hidden" name="how_max_global" value="0"/>

You may also want to show the app on a percentage of page views.  Use the following parameter to control this features:

<input type="hidden" name="how_percent" value="50"/>

A last parameter that can be included in the deploy button is a suggested PREVIEW URL that users will be shown the app when clicking the PREVIEW button.  Syntax is:

<input type="hidden" name="test_url" value="http://www.wikipedia.org"/>

An Example

Let's create an example where we want to deploy the Image Switcher app with some parameters.

<link type="text/css" href="http://siteapps.com/css/sa_window.css" rel="stylesheet"/>
<script type="text/javascript" src="http://siteapps.com/js/sa_window.js"></script>
<form method="post" action="https://siteapps.com/api/deploy" target="sa_win_deploy">
<input type="hidden" name="app_id" value="http://siteapps.com/app/image_switcher-22"/>
<input type="hidden" name="param_1" value="174px-Wikipedia_wordmark.svg.png"/>
<input type="hidden" name="param_2" value="http://siteapps.com/img/logo_sa.png"/>
<input type="hidden" name="when_always" value="1"/>
<input type="hidden" name="who_include_1" value="New Visitor"/>
<input type="hidden" name="how_max_visit" value="1"/>
<input type="hidden" name="where_include_1" value="http://www.wikipedia.org"/>
<input type="hidden" name="test_url" value="http://www.wikipedia.org"/>
<input type="button" id="sa_deploy_button" value="Deploy this app" onclick="sa_post(this)"/>
</form>