Redirection patterns can automatically and dynamically alter where an awe.sm link points. This feature allows metadata stored with an awe.sm link to be passed to your website when an awe.sm link is clicked. It also allows for the
original_url parameter to be a canonical field independent of where the end user is ultimately redirected.
Redirection patterns are managed through the Link Builder in your project settings. Access these settings by logging into the awe.sm web app and selecting the Settings pulldown. Redirection patterns are dynamically applied based on the hostname of the
original_url specified at the time of an awe.sm link's creation. Only one redirection pattern per hostname can be enabled at a time.
|An awe.sm link is created.|
|The link is posted to Twitter. It gets clicked.|
|A redirection pattern for awe.sm links redirecting to the domain mysite.com has been enabled.|
|A new URL is assembled according to the redirection pattern using data provided when the awe.sm link was created.|
The user is then redirected to the new URL.
The website now can use data captured from the original share action.
Example Use Cases
- Dynamically display the sharer's user name and profile image on the page shared to the visitor referred to your site by an awe.sm link.
- Pass an awe.sm link's campaign, channel, click referrer, and tool information as Google Analytics utm_campaign, utm_medium, utm_source, and utm_content parameters.
- Automatically append your Amazon Associates ID to awe.sm links redirecting to amazon.com.
- Promote Twitter or Facebook sharing buttons over one another based on how the visitor was referred to your site.
With the exception of %original_url% and %escaped_original_url%, all parameters will be URL escaped and trimmed to 128 characters. Any missing values will use the default value of an empty string except where specified.
The following parameters can be added at the time of link creation:
|%awesm_url%||The full awe.sm-powered tracking link as a valid URL, i.e.,
|%awesm_id%||The sanitized form of the awesm_url with any /s replaced by _s, e.g.
|%domain%||The custom domain on which the awesm_url was created.|
|%path%||The extension of the awesm_url, i.e. the part after the domain.|
|%created_at%||The timestamp of when the awesm_url was originally created, in ISO 8601 form. (Note: In cases like when a post is scheduled, the
|%escaped_original_url%||The full submitted
|%channel%||The most granular value for the means by which the awesm_url is being shared, see Channels and Services.|
|%service%||The 'service' value corresponding to the specified
|%tool%||The label corresponding to the specified
|%parent%||The awesm_id form of the specified
|%service_userid%||The numerical (i.e., immutable) identifier of the profile (e.g., Twitter user ID, Facebook profile ID, Facebook page ID, etc.) on whose behalf the awesm_url was shared. Takes the form %service%:%user_id%.|
|%campaign%||The sanitized (i.e. a-z0-9_-) label for a project-specific grouping of awesm_urls.|
|%campaign_name%||The human-readable (i.e., with capitalization, spaces, and special characters) name associated with a given
|%campaign_description%||The description text associated with a given
|%user_id%||A project-specific user identifier for the individual who initiated the share. (We recommend using an immutable user identifier, like a numerical user_id.)|
|%user_id_username%||The human-readable name associated with a given
|%user_id_profile_url%||A link to the user profile page associated with a given
|%user_id_icon_url%||The address of the user profile image associated with a given
|%tag%||An arbitrary string that is queryable in the Stats API.|
|%notes%||An arbitrary field that is not queryable in the Stats API. (i.e., is only available on a per awesm_id basis). Can be passed a json payload to be read by an external application or a set of query string parameters to be added in a redirection pattern.|
The following parameters can be specified after a link has been created via the Update Endpoint:
|%updated_at%||The timestamp of when the awesm_url was last updated, in ISO 8601 form.|
|%service_postid%||The numerical (i.e., immutable) identifier of the post (e.g., Twitter status ID, Facebook post ID, etc) in which the awesm_url was shared. Takes the form
|%shared_at%||The timestamp of when the post containing the awesm_url was shared, in ISO 8601 form. (Note: In cases like when a post is scheduled, the
|%reach%||The number of fans, friends, followers, etc., of the profile on whose behalf the awesm_url is shared (i.e.
The following parameters can be applied at the time of redirection (click):
|%referrer%||The full referrer string from which the visit is entering. If NULL, value is |
|%referrer_domain%||The hostname of the referrer string from which the visit is entering. If NULL, value is |
|%clicker_id%||The awe.sm cookie GUID for the visitor.|
If the URL being shared (i.e., submitted url) already contains query string parameters, we apply the following rules to deconstruct and sanitize the submitted_url value before applying the applicable redirection pattern:
- If the submitted url is a valid
awesm_url, use the
original_urlvalue of the submitted
original_urland make the submitted
- If the
submitted_urlcontains a valid
awesm=parameter, the value of this parameter will be used as the parent unless a parent value is explicitly specified; and if the awesm append rule is active for that
awesm=parameter will be removed from the
- If the submitted url has query string parameters that match any in the redirection pattern configured for that
original_urldomain, they will be removed from the
original_urlso as not to conflict with the outgoing parameters.
- If there is no redirection pattern configured for the domain of the submitted url, the full submitted url value gets stored as the
Note: When a submitted url contains query string parameters and there is a redirection pattern configured for that
original_url domain, the merged query string parameters (i.e., the ones on the submitted url and the ones from the redirection pattern) have no guaranteed ordering.
404 Pass Through
Redirection Patterns apply on all valid links for a given project. But in the case that a user enters an invalid link on your custom domain, you can use a special-case Redirection Pattern parameter for 404 redirects.
%path% parameter in the case of a 404 error can be used to pass through the unrecognized portion of the link after the domain (e.g., if a user types in
%path% value is
The most common use-case for the
%path% parameter on 404 is when you want to be able to use known paths on your primary domain with your awe.sm-powered domain. For example, our primary site is on totally.awe.sm and we use the awe.sm domain for redirect tracking. So, we use the redirection pattern
http://totally.awe.sm/%path% to make links like
awe.sm/jobs automatically redirect to
totally.awe.sm/jobs (try it: http://awe.sm/jobs). Unlike known
awesm_urls generated via our Create API, these 404 pass-through links aren't tracked (and if your destination site doesn't use case-sensitive paths, neither will these).
To use this feature, just add the
%path% wildcard in the 404 Redirect field in your Domain Settings.
"Ok," you say, "I see the value of using these parameters, but they mess with how crawlers index my site or screw up the functional parameters I use." Well, here are a couple things you can do on your end to deal with those issues:
- Canonical URLs
- Google, Yahoo!, and Microsoft have all agreed to start looking for the
canonicalmeta tag to keep from indexing duplicate content. It's kind of like a 301 HTTP redirect for crawlers without your losing the parameters you're passing into your dynamic pages. You can read all about it here.
- If you're down with the canonical, here are plugins for WordPress, Drupal and Magento that will do all your canonical-ing for you automagically.
- Google, Yahoo!, and Microsoft have all agreed to start looking for the
- Here's a code snippet that can be customized to remove non-functional parameters on page load.
Last updated 2012-10-19