Passing URL Parameters and Tracking Codes--for Advanced Users and Developers
Salsa Engage Forms enables you to pass in parameters from external URLs so that you to pre-populate a lot of info on forms that supporters link to from URLs external to Salsa Engage.
You can use this functionality with any Salsa Engage Activity. Here's how it works:
- Find the names of the parameters you want to pre-populate on your Salsa Engage Activity form.
- Write the URL, including parameters.
- Use the URL as a link (or for a button) on the web page that will call the Salsa Engage form.
Find Parameter Names and Set Hidden and Required Conditions
Each form field on a Salsa Engage Activity page has a parameter name (this includes custom fields). You'll need the parameter names of the Salsa Engage fields that you want to pre-populate so you can include them in the inbound URL. To find parameters name for form fields...
- Open the Compose tab for the Activity that has the form that you want to pre-populate.
- Click the edit pencil icon to open the edit window for the field.
- In the bottom of the right Preview frame, copy the Parameter name. Paste it to an MS Word or TXT document so that you can refer to it when you are creating your URL. Repeat this for every field that you want to pre-populate. Note, parameter names for standard Salsa Engage form fields are default. Custom Fields use parameter names that you include when you create a Custom Field. Once you create a parameter name for a Custom Field, it may not be modified. Click here for information about creating Custom Fields.
- Some fields enable you to define them as hidden and required.
- Hidden fields are useful when you want to track information about forms while not including fields that are not needed by supporters.
- Required fields are those which the support must fill out to proceed with your form. While getting data from supporters is invaluable, having too many required fields will potentially annoy and scare off supporters.
- Click Save Content to save your Hidden and Required setting and close the Edit Field window.
Use One-off Parameter Names
Salsa Engage also gives you the ability to enter your own, one-off parameter names for a specific form:
- Go to the Compose tab of your form, and click Confirmation View.
- Ensure that the Send them to a new page radio button is selected.
- In the field that contains Insert redirection URL, enter the URL of the page that you want to pre-populate.
- Ensure that the Append URL with form field parameters and data switch is ON.
- Check ("Select") the fields that you want to change Parameter Names for. The Parameter Name field will be enabled.
- Enter the Parameter Name that you want to use.
- Click Save. The Export button becomes active so you can Export the list of parameters to a CSV file if you wish to do so. Continue the Salsa Engage process.
Write the URL
The URLs that you create will follow the standard query string conventions detailed here. The format for query strings are as follows:
In this string...
- [Parameter] refers to the parameter for the field that you want to pre-populate on your Salsa Engage form.
- [Value] refers to the string that you want to include.
amount refers to the amount of the donation. When you have donation option buttons, enter the amount that you would like to be selected by default. For an optional amount, enter an amount not shown on a button. Although this will set a default selection, the supporter will still be able to choose or enter the amount they prefer.
recurring denotes whether the donation will be recurring or not.
A complete query string might look like this:
In this example, the parameters are person-firstname, person-lastname, amount, and receive-updates. The values are John Boy, Walton, 25, and yes.
This string uses the following symbols:
- ? - Use the question mark only after the URL. It indicates that what follows is a query string.
- = - Use the "equals" sign to indicate with what the field for the parameter that you enter should be populated.
- space - Use a blank space when a parameter has more than one word: for example, "Fall Gala" would be written as Fall Gala.
- & - Use the ampersand to concatenate multiple parameters/value combinations.
Salsa Engage prepends an abbreviation of the activity for some parameter names. This isn't something you need to worry about. The information is included here in case you come across a parameter prefix and are curious about what it means:
- sub_ - sign up form
- fun_ - fundraising form
- pet_ - petition
- act_ - targeted action
- evt_ - event
- p2p_ - peer to peer event
- gen_ - general
Salsa Tracking Codes
Salsa Engage enables you to add a Salsa Tracking Code parameter to your URLs. You'll be able to see and compare "Views" and "Conversions" metrics in your activity results to measure which code is performing the best for that activity.
To use a Salsa Tracking Code, simply add the following field-value pair to your URL query string:
A URL with a tracking code would look like this:
Salsa Tracking Code data will also be available in activity and transaction CSV export files in the "Salsa Track" column.
Use the URL for an External Link or Button
After you've created your URL, use it as link or button from the site from which you are linking to your Salsa Engage form. When a supporter clicks the link, the Salsa Engage form will open and be pre-populated with the data you've included in the URL. Be sure to test to make sure you are getting the results that you expect.