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.
• Javascript Bar API
• bar.show• Configuration Object
• bar.hide
• bar.initialize
rule• CSS
matchObject
matchParameter
parameter
actionObject
Putting it all together
.addthis_bar_container• Advanced Examples
.addthis_bar_message
.addthis_bar_button
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:
- Write your own business logic, and directly show the bar whenever you desire, customizing its appearance in its invocation
- 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/250/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"]
|
| mobile | bool | Accepts a boolean to match against for mobile |
// show to a user on a mobile device
mobile: 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 */ |
| 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 */ |
| iframe | bool | Tests against a boolean for whether the bar is in an iframe. |
/* never show the bar when loaded in an iframe */ |
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 | |
| 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 |