Sign up now 30 days free. Cancel anytime.

Have questions? Talk to us.

877-OK-AWESM  877-OK-AWESM Live chat Live chat developers@awe.sm developers@awe.sm Schedule a webinar Schedule a webinar

Redirection Patterns

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.

Process Overview

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.

Available Parameters

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.

Create Metadata

The following parameters can be added at the time of link creation:

Name Description
%awesm_url% The full awe.sm-powered tracking link as a valid URL, i.e., http://%domain%/%path%.
%awesm_id% The sanitized form of the awesm_url with any /s replaced by _s, e.g. planca.st_cp for an awesm_url of http://planca.st/cp.
%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 created_at values will be different from shared_at. The shared_at value is generally the more useful one.)
%original_url% The submitted url value stripped of any query string parameters that conflict with those in the redirection pattern.
%escaped_original_url% The full submitted url value in escaped form for use in the query string.
%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 channel, see Channels and Services.
%tool% The label corresponding to the specified tool key, see Tools and Applications.
%application% The application label corresponding to the specified tool key, see Tools and Applications.
%parent% The awesm_id form of the specified parent, which is the awesm_url that drove the creation of this one.
%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.
%campaign_description% The description text associated with a given campaign.
%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.
%user_id_profile_url% A link to the user profile page associated with a given user_id.
%user_id_icon_url% The address of the user profile image associated with a given user_id.
%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.

Update Metadata

The following parameters can be specified after a link has been created via the Update Endpoint:

Name Description
%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 service%:%post_id%.
%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 shared_at and created_at values will differ. The shared_at value is generally the more useful one.)
%reach% The number of fans, friends, followers, etc., of the profile on whose behalf the awesm_url is shared (i.e. service_userid) at the time it was shared (i.e., shared_at).

Click Metadata

The following parameters can be applied at the time of redirection (click):

Name Description
%referrer% The full referrer string from which the visit is entering. If NULL, value is direct-%domain%
%referrer_domain% The hostname of the referrer string from which the visit is entering. If NULL, value is direct-%domain%
%clicker_id% The awe.sm cookie GUID for the visitor.

original_url Canonicalization

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:

  1. If the submitted url is a valid awesm_url, use the original_url value of the submitted awesm_url as the original_url and make the submitted awesm_url the parent.
  2. If the submitted_url contains 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 original_url domain, the awesm= parameter will be removed from the original_url.
  3. If the submitted url has query string parameters that match any in the redirection pattern configured for that original_url domain, they will be removed from the original_url so as not to conflict with the outgoing parameters.
  4. If there is no redirection pattern configured for the domain of the submitted url, the full submitted url value gets stored as the original_url.

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.

The %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 http://awe.sm/foobar, the %path% value is foobar).

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.

Target Pages

"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 canonical meta 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.
  • JavaScript Cleanup

Last updated 2012-10-19