leads_integration
Differences
This shows you the differences between two versions of the page.
|
leads_integration [2010/08/06 18:08] bradley |
— (current) | ||
|---|---|---|---|
| Line 1: | Line 1: | ||
| - | ====== Lead Routing Integration Guide ====== | ||
| - | |||
| - | The ChannelSUITE Lead Routing Integration function provides the ability to generate leads for your channel from an "information request" form on your public website. A potential customer can inquire about certain products directly from your public website, and the Lead will then be stored and routed based on pre-defined routing rules for new Leads. | ||
| - | |||
| - | ==== Technical Overview ==== | ||
| - | |||
| - | The approach is this: you supply a form on your website and POST the form to our server. The information entered on the form will then be stored and routed based on pre-defined routing rules. There are certain required fields (see “required fields” below) that we require in order to get the process started. There are optional fields that are available to you if you want to capture extra information about the prospective Lead (see “optional fields” below). View [[LD-example| sample code here]] for a form that utilizes all fields available. There are also required hidden fields that need to be added into the form in order for our server to be able to save and route the newly entered Lead. | ||
| - | |||
| - | ==== Integration Steps ==== | ||
| - | - request a free directPostKey from your channelSUITE account manager | ||
| - | - include the necessary javascript files | ||
| - | - set up form using specified field names and field IDs | ||
| - | - add the hidden yourEmail field to the form to discourage spambots | ||
| - | - set the form ACTION to send form submissions to your channelSUITE install | ||
| - | - test the form using the built-in test mode | ||
| - | - turn off test mode | ||
| - | |||
| - | more details on these steps are shown below | ||
| - | |||
| - | ====Javascript Includes==== | ||
| - | |||
| - | several javascript files are needed to set up client-side validation and the country-specific state/province select box. all the files can be loaded from the channelsuite server as shown, or if you prefer you can download the files and host them on your server. //Note: The stateProvinceMap technically contains dynamic data, but it only changes if support for states/provinces is added for an additional country in your channelsuite database, so in practice you may treat it as a static file.// | ||
| - | |||
| - | add this in the <head> section of your html | ||
| - | |||
| - | <code html> | ||
| - | <!-- CHANNELSUITE REQUIRED --> | ||
| - | <script type="text/javascript" src="http://yourChannelsuiteURL/API/js/prototype.js"></script> | ||
| - | <script type="text/javascript" src="http://yourChannelsuiteURL/API/js/leadsForm.js"></script> | ||
| - | <script type="text/javascript" src="http://yourChannelsuiteURL/API/js/stateProvinceMap.js.cgi"></script> | ||
| - | <script type="text/javascript" src="http://yourChannelsuiteURL/API/js/stateWidget.js"></script> | ||
| - | <!-- end CHANNELSUITE REQUIRED --> | ||
| - | </code> | ||
| - | |||
| - | ====Form Contents==== | ||
| - | |||
| - | Notes: | ||
| - | - All fields names are case sensitive. | ||
| - | - When using ampersand characters in select/hidden field values, do not entity encode. | ||
| - | |||
| - | === REQUIRED fields === | ||
| - | |||
| - | The following fields are required in order to create a new Lead: | ||
| - | |||
| - | * Company Name - the name of the company looking for information on your products | ||
| - | <code html> | ||
| - | <input value="" name="company" type="text" id="company"> | ||
| - | </code> \\ | ||
| - | * Contact - the first and last name of the contact so we know who to get in touch with | ||
| - | <code html> | ||
| - | <input value="" name="contact" type="text" id="contact"> | ||
| - | </code> \\ | ||
| - | * E-Mail - the e-mail address of the contact belonging to the company | ||
| - | <code html> | ||
| - | <input value="" name="email" type="text" id="email"> | ||
| - | </code> \\ | ||
| - | * Phone - the phone of the contact belonging to the company | ||
| - | <code html> | ||
| - | <input value="" name="phone1" type="text" id="phone1"> | ||
| - | </code> \\ | ||
| - | * Country - the country in which the company requesting information is located. See below for more information about standard country codes. Note: the “onchange” event handler is only required if you use a state/province field in your form (recommended if you service customers in US or Canada) | ||
| - | <code html> | ||
| - | <select id="countryCode" name="countryCode" onchange="stateWidgetCallback();"> | ||
| - | option tags go here, see below | ||
| - | </select> | ||
| - | </code> \\ | ||
| - | |||
| - | === OPTIONAL fields === | ||
| - | |||
| - | The following fields are optional in order to record more information about the prospective company requesting information: | ||
| - | |||
| - | * Interest - what product are you mainly interested in | ||
| - | <code html> | ||
| - | <input value="" name="interest" type="text"> | ||
| - | </code> \\ | ||
| - | * Campaign - is this Lead assigned to any Campaign that the prospective customer may have been to | ||
| - | <code html> | ||
| - | <input value="" name="campaign" type="text"> | ||
| - | </code> \\ | ||
| - | * Referral - how did the prospective customer hear about your business | ||
| - | <code html> | ||
| - | <select name="how"> | ||
| - | <option value="">Make a Selection</option> | ||
| - | <option selected="selected" value="Referral">Referral</option> | ||
| - | <option value="I am a customer">I am a customer</option> | ||
| - | <option value="Trade Show">Trade Show</option> | ||
| - | <option value="Company Website">Company Website</option> | ||
| - | <option value="Search Engine">Search Engine</option> | ||
| - | <option value="Trade Publication">Trade Publication</option> | ||
| - | <option value="Other">Other</option> | ||
| - | </select> | ||
| - | </code> \\ | ||
| - | * Street - street address of prospective customer | ||
| - | <code html> | ||
| - | <input value="" name="street1" type="text"> | ||
| - | </code> \\ | ||
| - | * City - city of prospective customer | ||
| - | <code html> | ||
| - | <input value="" name="city" type="text"> | ||
| - | </code> \\ | ||
| - | * State/Province - the code for the state or province of prospective partner. Leave an empty element with ID “statecell”, this will be filled in dynamically by the stateWidget javascript. See below for more information on setting up the state/province codes. | ||
| - | <code html> | ||
| - | <span id="statecell"></span> | ||
| - | </code>\\ | ||
| - | * Postal Code - postal code of prospective customer | ||
| - | <code html> | ||
| - | <input value="" name="zip" type="text"> | ||
| - | </code> \\ | ||
| - | * Comments - any other comments that the prospective customer may want to share | ||
| - | <code html> | ||
| - | <textarea name="custom_flds" cols="80" rows="5"></textarea> | ||
| - | </code> \\ | ||
| - | * apiFlag - this flag is used to receive back an xml stream once the form has been submitted | ||
| - | <code html> | ||
| - | <input value="1" name="apiFlag" type="hidden"> | ||
| - | </code> \\ | ||
| - | |||
| - | === REQUIRED hidden fields === | ||
| - | |||
| - | The following hidden fields are required in order to save the information to the database: | ||
| - | |||
| - | * directPostKey | ||
| - | * The value of this field must match the directPostKey assigned to you on the server. Please ask your account manager to get you a "directPostKey”. | ||
| - | <code html><input type="hidden" name="directPostKey" value="authenticated"></code> | ||
| - | |||
| - | === OPTIONAL hidden fields === | ||
| - | |||
| - | * saveRecord | ||
| - | * the following hidden field is used for testing your form. when this hidden field is set to 0, submitted form contents are echoed back to the screen and are NOT submitted to the channelsuite recruit database. if this field doesn't exist or is set to any value other than 0, the form is processed normally. | ||
| - | <code html><input id="saveRecord" name="saveRecord" value="0" type="hidden"></code> \\ | ||
| - | * apiFlag | ||
| - | * this flag is set when you want to have returned to you an xml stream of the results after submission. By setting this flag, the thank you page will not be displayed after the lead has been successfully submitted. The following is what can be expected once the lead has been saved: | ||
| - | * For a successful entry: | ||
| - | <code html> | ||
| - | <response> | ||
| - | <result>1</result> | ||
| - | <leadId>2133</leadId> | ||
| - | </response></code> \\ | ||
| - | Where leadId is the primary key of the lead that was just created. | ||
| - | * source | ||
| - | * this field is used when you have multiple public forms submitting new leads. once a form is submitted, the forwarding URL is retrieved from the directPostThankYouURL setting. this source variable is then appended to this URL as a parameter so that your public web site that processes this URL can distinguish from which page this lead has been submitted. an example of how this URL would look with the source attached is as follows: \\ | ||
| - | if your config setting is: | ||
| - | directPostThankYouURL = 'http://myPublicWebsite.com/lead_return/' | ||
| - | and your form's source variable is set in a hidden field like this: | ||
| - | <input name="source" value="publicSite1" type="hidden"> | ||
| - | then after submitting the form, the user will be redirected to this URL on your site: | ||
| - | http://myPublicWebsite.com/lead_return/?source=publicSite1 | ||
| - | |||
| - | === CUSTOM fields === | ||
| - | |||
| - | In the event that you want to capture more information than the fields outlined above, you can also add in your own custom fields which will be saved into the Comments field in the record. Should you have two custom fields, namely: \\ | ||
| - | <code html><input type="text" name="custom_1" value="Custom field 1"></code> | ||
| - | <code html><input type="text" name="new_field" value="A new field"></code> | ||
| - | The following will be appended to the Comments field: \\ | ||
| - | custom_1: Custom field 1 \\ | ||
| - | new_field: A new field \\ \\ | ||
| - | The name of the field will be entered first, followed by a colon (:) and then the value the user entered. Any of these extra fields will be added to the end of any existing Comments already entered. A new line will separate multiple user defined custom fields. | ||
| - | |||
| - | === Anti-spam: the yourEmail hidden field === | ||
| - | |||
| - | Forms on public websites are often targets for "spambots" -- automated "spiders" that wander around the web looking for forms. The spambot puts its irrelevant message in whatever fields it can find, and submits the form in the hopes that the posted content will show up somewhere where it will be seen. These submissions would show up as bogus entries in your leads database. Quite annoying. | ||
| - | |||
| - | Spambots aren't very sophisticated, and they can be effectively defeated by using a "captcha", the most common example being to ask your users to type in the text from a distorted text image. This works, but it's irritating to your users. We're using a simpler method called a "honeypot". We add a field to your form that users can't see, but that the spambots can't easily identify as a hidden field. The spambots will typically insert content into this field. If the field isn't empty, it's usually a spambot submission, and we reject it with an appropriate error message. It contains a label that instructs users of alternative browsers (handicapped-accessible screen readers, for example) to leave the field empty. This method is very effective, and causes no problems for legitimate users. | ||
| - | |||
| - | To implement the honeypot, simply add the following hidden span containing the empty field yourEmail in your form: | ||
| - | <code html> | ||
| - | <span style="display:none;visibility:hidden;"> | ||
| - | <label for="yourEmail"> | ||
| - | Ignore this text box. It is used to detect spambots. | ||
| - | If you enter anything into this text box, your submission | ||
| - | will be rejected. | ||
| - | </label> | ||
| - | <input type="text" name="yourEmail" size="1" value="" id="yourEmail" /> | ||
| - | </span> | ||
| - | </code> | ||
| - | |||
| - | === Setting Up the Country Code Select Box=== | ||
| - | |||
| - | Channelsuite uses a normalized list of standard country codes. The list of country codes used in your channelSUITE install can be found by running the "country list" API as described in [[api_helper_functions]]. Just copy and paste this list of html <option> tags (or a subset if you don't recruit globally) into the countryCode <select> container. | ||
| - | |||
| - | ===Setting up the State/Province Code Select Box=== | ||
| - | |||
| - | If you provide service in countries such as US and Canada where states or provinces are commonly used, you'll want to use the channelSUITE list of normalized stateProvinceCode values for that country. But this is even trickier than the countryCode select box, since the list of states/provinces is country-specific. The good news is, all the steps necessary to make this work have already been covered above: | ||
| - | - load the stateProvinceMap and stateWidget javascript files | ||
| - | - set the "onchange" on the countryCode field | ||
| - | - provide a <span> or table cell with id="statecell" for the javascript to insert the state/province select box. | ||
| - | |||
| - | Now your form will dynamically provide the correct state/province field options for the chosen country, based on the list of supported countries in your copy of the channelSUITE database. | ||
| - | |||
| - | ====Testing Your Form==== | ||
| - | |||
| - | set the hidden field saveRecord value=0 and submit. you should see the correct form values echoed back. make sure to check that the state/province field options look right for countries that use standard states or provinces (by default we support US, Canada, and Mexico, but you may request others). when you're ready to go live, change saveRecord to value=1. | ||
| - | |||
leads_integration.1281118130.txt.gz · Last modified: 2010/08/06 18:08 by bradley