5.7 Merged Parameters within URLs
URL parameters are specially constructed parts of a Web address (URL) that allow that single URL to initiate various specific operations by passing particular instructions and data to the Web server. Parameters are text based instructions and data that are passed to a Web server, which passes them on to a script, (for example, a Java, Perl, C/C++, or a UNIX shell script). The script then executes the corresponding parameter as instructed by the URL, and passes the results back to the Web server. The Web server then returns the results to the client. In essence, parameters can be used to select a certain page or part of a page to display, or tell the server which page to display to a specific user or type of user.
A URL-parameter is a pair like "name=value" which appears after the path-part of the URL, separated from the path by a question mark "?", like the example below:
If there are several parameters in one URL, then the individual parameters are separated by ampersand characters "&":
Different visitors would have different values of the "visitorID" parameter. For example, the following URL would tell the server that this time the visitor has the ID "usr217":
LISTSERV Maestro allows the user to track URLs with or without parameters as well as URLs with constant or individual parameters. Since URLs with individual parameters need to have a different value for the parameter for each recipient, how can such a URL be written in the text of the message?
By using field merging, it is possible to create unique URL parameters based on the fields of a database. For example, assume there is a merge field named "ID" for each recipient that contains the visitor ID of that recipient, then the sample URL of above would be written as:
Let us dissect the different parts of this example:
The URL begins as the usual protocol header, the host name and the URL-path:
Next follows the the question mark, signaling the end of the path-part and the beginning of the parameter-part:
The first parameter is the parameter "visitorID" with the value "&ID;":
Between the first and second parameter is the ampersand as a separator:
Thesecond parameter is the parameter "page" with the value "home":
The second part of the first parameter "visitorID=&ID;" uses the LISTSERV Maestro convention of denoting mail merge fields. Its value is not an actual user ID, but instead is the name of the merge field "ID", with the preceding ampersand and the trailing semicolon, (which are always used in LISTSERV Maestro to mark mail merge fields).
Although the ampersand usually has the reserved function of separating two parameters (like the second ampersand right before the "page" parameter), when it appears to denote the merge field "&ID;" it is acting as a token that will be replaced by the corresponding value of the recipient before the mail is sent out. Therefore, this string will not be present in the final e-mail that appears to the recipient; instead it will have been replaced by the merge value of that recipient.
By employing LISTSERV Maestro’s mail merging features, it is possible to insert URLs that contain constant and individual parameters for each recipient into e-mail messages.
LISTSERV Maestro is able to track all of these URLs if they are marked for tracking. As a result, if a URL that contains a merged parameter is selected for tracking, LISTSERV Maestro will count all clicks of all recipients on this URL, and each recipient will be directed to the actual URL using his or her own individual parameter.
In the e-mail messages that are sent out, the URL is replaced by a special tracking URL, that points to the server running the Maestro Tracker component, so that LISTSERV® Maestro can count each click on the URL and then redirect to the actual target URL.
Each user that clicks on this tracking URL will be counted and will be redirected to the actual target URL, using the URL-parameters for that user. For example, the server at "host.domain" will receive the correct "visitorID=usr15" and "page=home" parameters (for other recipients, the "visitorID" would have different values).
URL-parameters may only contain characters that are safe to use in a URL. Some characters are not safe to use, other characters have a reserved meaning (such as, for example, the ampersand (&), which has the special meaning of separating two parameters). Therefore, all characters that are not valid for use in a URL parameter value must be "URL-encoded". URL-encoding is a standard that encodes unsafe characters into safe characters.
When using field merging in URL parameters, there are two options to ensure that all parameters are URL-safe:
The function "&*URLENCODE(&ID;)" tells LISTSERV to retrieve the value of the "&ID;" merge field, then apply the "&*URLENCODE()" function to it, that is to encode all unsafe characters, and then merge in the result in place of the whole "&*URLENCODE(&ID;)" string.
Important Note: The parameter name "ref" is a reserved name that is used by LISTSERV Maestro to transfer the tracking information to the Maestro Tracker component (seen in the example above). Therefore"ref" cannot be used in any parameters if there are also merge fields in the same URL. If a URL looked like:
This URL contains two parameters with the name "ref". One comes from the original URL, while LISTSERV Maestro added the other. These two parameters with the same name would confuse the Maestro Tracker component. Therefore, a parameter called " ref" must never be used if there are merge fields used in the URL.
Since the parameters are also replaced by the tracking URL, it does not matter whether the parameter list contains a parameter called "ref" or not. However, this is only true if no merge field is used in the parameter list, meaning that there are only constant parameters.