Support

Welcome Bar API

This reference can be read sequentially like a guide; we build on simple concepts before we get to the full power of the API. You can also use the direct links below to access specific method and property definitions. Prefer to just jump right in and hack? Check out our advanced examples.

Overview

The Welcome bar appears at the top of the page offering your users a simple call to action, such as to share this page or to link to a specific section of your site. You can display custom messages based on referrer (a blog linking to you, for instance) or to automatically offer visitors their preferred sharing method. In fact, thanks to the AddThis data API, you can tailor the Welcome bar very specifically to your visitors using criteria as diverse as their geolocation, preferred social networks, and more.

It's in a public beta right now, so please do let us know what you think.

How it works

You place the Welcome bar code on any page. Whenever a visitor arrives on the page, we'll check to see if they're a match for one of the criteria you've defined. (You can also define no criteria, so that the bar is shown to everyone.) If we find a match, we'll show the bar you configured at the top of the page.

What the bar shows

The bar shows a specific text message and call to action for each match configuration. At present, there are three different calls to action: share (invite the user to share using our regular sharing tools), follow (invite the user to follow you using our regular follow tools), or link (invite the user to go to a specific link).

An illustrative example

Before we dive into how it works, take a look at the code for a simple bar:

addthis.bar.initialize({
    "message": "Do you want a welcome bar?",
    "action": {
        "type": "button",
        "text": "Yes!",
        "verb": "link",
        "url": "http://addthis.com/get/welcome"
    }
});

Not too crazy, right? Now see how it renders.

 

JavaScript Bar API

Because the bar's appearance is generally conditional, you must write JavaScript to invoke it. You have two options:

  1. Write your own business logic, and directly show the bar whenever you desire, customizing its appearance in its invocation
  2. Harness our data APIs and configure the bar to vary its behavior under criteria you set

Either way, you include our standard code first:

<script type="text/javascript" src="http://s7.addthis.com/js/300/addthis_widget.js#username=your-username"></script>

Although we believe you'll generally want to use our powerful data API, we'll start out demonstrating the simplest way to use the bar: showing it with a specific configuration of your choosing.

bar.show([configuration])

Shows the bar. If a bar configuration object is passed in, the bar will be automatically updated with that configuration.

/* We define the bar configuration parameters below.
   For now, just follow along. */
addthis.bar.show({
    message: "An example", /* Bar displays immediately, with the message "An example" */
    action: {
        "type": "button",
        "text": "Show me",
        "verb": "link",
        "url": "http://www.example.com" /* . . . and a button labeled "Show me" */
    }
};
Show me this example
 


bar.hide()

Hides the bar if it's currently being shown.

addthis.bar.hide();
Hide any example bar
 
 

An interlude

It should now be apparent how you could write your own business logic to show or hide the bar based on criteria that were relevant to your app. For example:

if (myApp.state.userType == 'thebest') {
    addthis.bar.show({
        message: "You are my favorite user!",
        action: {
            "type": "button",
            "text": "Click for your just reward",
            "verb": "link",
            "url": "http://industryrockstars.com/wp-content/uploads/2011/09/milliondollars21.jpg"
        }
    };
} else if (myApp.state.userType == 'ambitious') {
    addthis.bar.show({
        message: "Anything is possible",
        action: {
            "type": "button",
            "text": "Proof",
            "verb": "link",
            "url": "http://zombo.com"
        }
    };
}

If that doesn't make sense, feel free to back up and make sure bar.show and bar.hide work for you. We're about to dive into the rich configuration API.

Why use the rich API? Most of the time, you probably care less about your own internal logic and more about customizing messaging to external conditions. For example, is this user a mobile user that I should show an app download promotion to? Is this user coming from the writeup I just got on TechCrunch? Is this user a heavy Twitterer?

To let the bar handle these decisions for you, you must initialize it with our robust configuration object.

 

bar.initialize([configuration])

Prepares the bar for conditional rendering. If you want to use our configuration system based on our data, this is the way to go. You can either specify a single configuration rule, an array of rules, or a full configuration object containing both rules and default state.

addthis.bar.initialize({
    /* Configuration object goes here. Explained in detail below. */
});
 

Configuration

Configuration! This is where the true power of the Welcome bar API is revealed. Sure, you could write endless case statements of your own, but most of the time using our native configuration options result in a more compact, readable and elegant solution. Our configuration object is just a plain old JavaScript object (so you could do fancy things like use JSON to serialize it from a configuration stored on your server).

Birds' eye view

The configuration object is made up of two key pieces: how to configure the bar by default (optional), and how to configure the bar in special cases your care about. We call these special cases rules. If we zoom out for a moment, the basic configuration appears as follows in the context of an bar.initialize call:

addthis.bar.initialize({
    default: {
        /* Default configuration. Applies every time the bar is rendered. 
           Useful to do things like define a global style for different bars.
        
           This is optional. It's configured exactly like a rule definition without any match 
           criteria, because, as a default configuration, it's always applied unless 
           overridden by a specific rule.
        */
    },
    rules: [{
        /* An array of bar instance configurations. We call them match rules because they're 
           applied under specific circumstances. For example, you might want to only show a 
           bar to returning users. That rule would say, "If a user is returning, 
           show them this bar."
        
           This is also optional. For example, if you just wanted to show the same message 
           to every user, every page view, you wouldn't need to define a rule. 
            You'd just have a default message defined above. 
        */
        ruleObject1,
        ...
        ruleObjectN
    }]
});

Note that for simpler cases (i.e., show a bar only if a single match condition applies), you can pass a ruleObject directly to bar.initialize.

The ruleObjects, in turn, take this basic form:

rule : {
    /* A rule has criteria for matching a specific user, defined below. 
       If the match field is omitted, then the rule will apply to every visitor. */
    match: matchObject, 
    
    /* A rule has a series of parameters, defined below, that say what to do 
       when the match criteria is satisfied. 
       For example, these parameters define what the bar's message is, its action, etc. */
    parameter1,
    ...
    parameterN
}

We'll define these in detail in a moment, but here's a concrete example:

rule : {
    /* If the referrer was slashdot.com . . . */
    match: {
        referrer: "slashdot.com"
    },
    
    /* show a message to the user . . . */
    message: {
        "Thanks for Slashdotting me!"
    },

    /* and invite them to click a link off your site. */
    action: {
        verb: "link",
        type: "button",
        url: "http://example.com",
        text: "Goodbye"
    }
}

The matchObject defines a set of match parameters to match, with their accepted values.

match : {
    matchParameter1 : matchParameterValue1,
...
    matchParameterN : matchParameterValueN
}

For example, a possible match parameter is "referrer"; it matches the page referrer. To match all visitors from Slashdot, your match object would look like this:

match : {
    referrer: "slashdot.com"
}
 

Before we dig into the possible match parameters and bar configuration parameters, let's put these all together to see the basic form of a total bar configuration:

addthis.bar.initialize({
    default: {
        // Here are my bar's default configuration parameters. 
        parameter1,
        parameter2
    },
    rules: [{ 
        // Here's my first rule
        match: matchObject,
        // Its configuration parameters will only be applied
        // when its matchObject applies to the current visitor.
        parameter1,
        parameter2
    }, {
        // Here's my second rule
        match: aDifferentMatchObject
        parameter1,
        parameter2
    }]
});

 

 

Match Parameters

Defining the criteria by which to match is a critical part of making your bar effective. You want to target specific users with calls to action that make sense to them. We support the following parameters for use as match parameters. When the current session matches all of the defined properties in a matchObject, its containing rule is applied. For example, to show a special message to users coming from the New York Times' website, you'd define a matchObject whose sole key compared the visitors referrer with "nytimes.com".

 

Name Type Description Example
referrer [string] A string, or array of strings, matching literal URLs ("http://t.co"). Each is treated as a RegExp. referrer: "example.com/cool/articles/.*"
url [string] A string, or array of strings, that test against the document.location.href. Each is treated as a RegExp. url: ["addthis.com/blog","addthis.com/get"]
query object An object of query parameter key-value pairs query: { status: "logged_in" }
utm_source string Tests the url for a matching Google Analytics utm_source tag utm_source: "social"
utm_campaign string Tests the url for a matching Google Analytics utm_campaign tag utm_campaign: "spring_sale"
utm_medium string Tests the url for a matching Google Analytics utm_medium tag utm_medium: "cpc"
utm_term string | [string] Tests the url for a matching Google Analytics utm_term tag utm_term: "running+shoes"
utm_term: ["running","shoes"]
utm_content string Tests the url for a matching Google Analytics utm_content tag utm_content: "textlink"
hasTag string | [string] Checks if you've tagged the visitor ( addthis.user.tag('sports') ), using logical OR in the case of an array hasTag: "sports"
hasTag: ["golf","soccer"]
hasTags string | [string] Checks if you've tagged the visitor ( addthis.user.tag('sports') ), using logical AND in the case of an array hasTag: "sports"
hasTag: ["golf","soccer"]
mobile bool Accepts a boolean to match against for mobile // show to a user on a mobile device
mobile: true
phone bool Matches a boolean against whether or not the user is on a phone phone: true
tablet bool Matches a boolean against whether or not the user is on a tablet tablet: true
socialBrowser bool Tests whether the user is viewing the page in a "socail" browser, e.g. clicking on a link in the Twitter iOS client. socialBrowser: true
desktop bool Accepts a boolean to match against for desktop browsing // don't show to a user on their desktop desktop: false
browser "internet explorer" | "ie" | "firefox" | "chrome" | "safari" | "opera" Accepts a string to select a specific browser // only show this bar to firefox users browser: "firefox"
custom function | bool Insert either a function or bool to evaluate. If true, the bar is shown. custom: function() { return true; }
/* or */
custom: myboolean // defined elsewhere in your app
sameDomain bool Tests against a boolean for whether the referrer is the same domain.  
returning bool Tests against a boolean for whether the visitor is returning or new to your site. any prior visit marks the user as "returning".  
referringService string Tests against a string for whether the user is coming from a given service referringService: "twitter"
usesService string Tests against a string for whether the user uses a given service usesService: "reddit"
preferredService string Tests whether a service is among the user's preferred services /* Show this bar to any user whose favorite service is pinterest */
preferredService: "pinterest"
iframe bool Tests against a boolean for whether the bar is in an iframe. /* never show the bar when loaded in an iframe */
iframe: false

Example matchObjects

User from Twitter
match: {
    referringService: "twitter"
}
 
User coming from another page on your site
match: {
    sameDomain: true
}
 

Bar Configuration Parameters

Once we've specified the match criteria for determining when to show the bar, we need to configure the bar.

Name Type Description Default value Required?  
action actionObject Every configuration must have a call to action associated with it. Today, the action defines the bar's button behavior. Eventually, you might be able to solicit a mailing list signup, ask the user to check an opt-in box, or other advanced actions. We define the action format below.   yes
message string The text of the message displayed on the bar.   yes
position string The physical position of the welcome bar on the page.  Possible values are "top" or "bottom" top no
backgroundColor string Background color for the bar, in hex. (You can also define your own CSS rules). Black no
textColor string Color for the bar's text. Should be a hex value White no
buttonColor string Background color for the button. Should be a hex value. Blue no
buttonTextColor string Text color for the button. Should be a hex value. White no
name string A name for the rule.   no
delay integer (seconds) Seconds to wait after pageload to display the bar 0 no
hideAfter integer (seconds) Seconds to wait after displaying the bar before hiding the bar. The default behavior is to not hide the bar automatically.   no
rememberHide boolean Determines whether the welcome bar, for a user who has minimized it, should remain minimized on subsequent visits. true no
showOnScrollTo element | string | integer | float Displays the bar once the user has scrolled a certain amount, either to a specific element or to a certain fraction of the page.   no
fixed boolean Determines whether to fix the bar to the top making it visible as the user scrolls false no
position string Where to position the Welcome bar, either the top or bottom of the window. Allowed values are "top" and "bottom" top no

Example

Show a message in garish colors
rule : {
    message: "Hi, I'm a bar.", 
    backgroundColor: "#ffff00", 
    textColor: "#000"
}
 
 

Bar Action Parameters

Today, there's only one type of bar action: the button. Buttons implement a verb (like sharing or linking), and each verb requires some specific metadata.

verb : "share" | "follow" | "link"

"share" shows a sharing button, "follow" a follow button, and "link" a button linking to a specified URL.

service : string

For "share" or "follow" buttons: determins what service to share to. If set to "preferred", will use the user's top share service, defaulting to Facebook where there is no share history.

text : string

Button text. Accepts limited templating, such as: "Share to {{service}}". {{service}} will be replaced with the service's full name.

url : uri

For "link" buttons: determines what URL gets opened.

id : string

For "follow" buttons. ID of account to follow; if passed with url and no service, equivalent to: window.open(action.url + action.id);

type : "button"

This declaration may be omitted, but will become significant in future iterations.

 
 

Example actionObjects

Basic share
action: {
    verb: "share",
    type: "button",
    service: "facebook",
    text: "Share this page!"
}
Basic link
action: {
    verb: "link;,
    type: "button",
    url: "http://example.com/hot-topic",
    text: "Read the article everyone is talking about"
}
Basic follow:
action: {
    verb: "follow",
    type: "button",
    service: "twitter",
    text: "Follow us on twitter!"
}
 


Putting it all together

Here's how we use all this configuration together.

Examples

Invite Facebook and Twitter users to share
addthis.bar.initialize({
    /* Specify default configuration. No message, just some colors. */
    default: {
        backgroundColor: "#eee",
        textColor: "#000"
    },
    rules: [{
        match: { 
            "service": "facebook"
        },
        "message": "Hey Facebook user! Share my page.",
        "action": {
            "type": "button",
            "text": "Share",
            "verb": "share",
            "service": "facebook",
            "url": "http://addthis.com"
        }
    }, {
        match: { 
            "service": "twitter"
        },
        "message": "Hey Twitter user! Tweet my page.",
        "action": {
            "type": "button",
            "text": "Share",
            "verb": "share",
            "service": "twitter",
            "url": "http://addthis.com"
        }
    }
]});
Show me this example (won't show if you don't use Facebook or Twitter, but we can fake it for you)
 


CSS

For your convenience, the major elements of the Welcome bar have CSS classes assigned so you can style them directly yourself.

.addthis_bar_container

The overall object. The message, the button, etc. all fit inside.

.addthis_bar_message

A <span> element containing the message.

.addthis_bar_button

A <button> element.

 

Example

Render a white bar with black text.

<style type="text/css">
addthis_bar_container: {
    background-color: white
}

addthis_bar_message: {
    color: black
}
</style>
 


Advanced Examples

Geolocation

Want to promote an event to users coming from a specific location? No problem -- we pay for expensive geolocation services so you don't have to.

Here's a simple example. Let's say you want to invite everyone from New York to an event. This bar will only pop up for people connecting to your site from within the state.

addthis.bar.initialize([{
    "match": {
    /* the "locatedIn" condition can match anything our data API"s 
addthis.user.isLocatedIn() method matches: a two-character region code (e.g., US states like "NY" or "DC") a two-character ISO-3166-1 country code (e.g., "DE" or "IT") a two-character continent code (e.g., "NA" or "EU") a five-digit US ZIP code (e.g., 20002) a comma-separated list of any of these to match multiple locations */ "locatedIn": "NY" }, "message": "Want to watch awesome videos from the 80s at VCR Party?", "action": { "type": "button", "text": "Take me there!", "verb": "link", "url": "http://foundfootagefest.com" } }]);

As described, the locatedIn condition is allows for extremely narrow targeting. If you're feeling extra exclusive, you can limit an invitation to your favorite ZIP code.

addthis.bar.initialize([{
    "match": {
        "locatedIn": "11201"
    },
    "message": "You are awesome.",
    "action": {
        "type": "button",
        "text": "Aw, shucks",
        "verb": "link",
        "url": "http://s4.hubimg.com/u/3660863_f520.jpg"
    }
}]);

Time and Date

Want to promote a special to early birds? You can have a bar display based on whether the user's visiting after some start time, before some end time, or both.

In this example, we'll show a special message to anyone arriving between 6 and 7:30 AM.

 

addthis.bar.initialize([{
        "match": {
            /* The "time" field can be used to specify a start time, an end time, or a range. If only the start time is present, any time after the indicated start, the bar will appear. If only the end time is present, the bar will appear as long as the end time hasn't arrived. You can define times using any of
            • HH:MM
            • HH:MM:SS
            • MM/DD/YY
            • MM/DD/YY HH:MM
            • or a native JavaScript Date object 
            If you only specify HH:MM, the bar will be displayed on every day during the window. So for example, a start time of "14:00" would result in a bar appearing every day at 2PM, and disappearing at midnight. */
            "time": {"start":"06:00", 
                 "end":"07:30"}
        },
        "message": "Wow, it's early! Have a coffee on us",
        "action": {
            "type": "button",
            "text": "All right!",
            "verb": "link",
            "url": "http://www.roaste.com/product/Avion-Coffee/Mystere-Espresso"
        }
    }
]);

New vs. Returning

Sometimes you might want to show different messages to users who have been to your site before, versus new users. It's not an exact science, since users can clear their cookies, but we keep track of who's been to your site and how often as best we can.

In this example, we'll invite every new user to follow you on Twitter, and any old user to reweet your content.

addthis.bar.initialize([
    {
        "match": {
            /* Any user who's been here before will see this bar. */
            "returning": true
        },
        "message": "Welcome back. Spread the word!",
        "action": {
            "type": "button",
            "text": "Tweet",
            "verb": "share",
            "service": "twitter",
            "url": "http://www.addthis.com"
        }
    }, {
        "match": {
        /* Any new user will see THIS bar. */
            "returning": false
        },
        "message": "Welcome to our site!",
        "action": {
            "type": "button",
            "text": "Follow us",
            "verb": "follow",
            "service": "twitter",
            "url": "http://www.twitter.com/addthis"
        }
    }
]);

Mobile vs. Desktop

Got an app for that? If your site has special mobile apps, you can promote them straight from the bar to users on mobile devices.

In this example, we'll show the user a download link for an iPhone app.

addthis.bar.initialize( [
    {
        "match": {
            "mobile": true
        },
        "message": "Bjork just released her new record as a mobile app.",
        "action": {
            "type": "button",
            "text": "Download",
            "verb": "link",
            "url": "http://itunes.apple.com/us/app/bjork-biophilia/id434122935?mt=8"
        }
    }
]);

Back to Top

Last Updated: Oct 23, 2013 01:52PM EDT
help@addthis.com
http://assets02.desk.com/
false
desk
Loading
seconds ago
a minute ago
minutes ago
an hour ago
hours ago
a day ago
days ago
about
false
Invalid characters found
/customer/en/portal/articles/autocomplete