At BASIK we’ve built social media widgets and integrations several times. And as with any task that involves multiple, changing technologies, there have been headaches every time. So in the interest of helping out others faced with similar tasks, this article describes our recent project with Attention for Barbie and The White House Project.
BUILDING THE WIDGET
The widget allows visitors to sign a petition. Their signature is stored in a database that can be searched from the widget. The widget has share features that let you email it to a friend, send a tweet about it, share it to Facebook and embed it in your blog or HTML page.
Our first step was to choose the technologies we would use for the project. Please note that you need not make the same decisions as us in order for you to glean value from this article. We simply wish to flesh out the narrative.
For the widget, we chose to use the Frontal language which is implemented in Flash. This was a prejudiced decision as we are closely involved in the development of Frontal but it’s also a decision that really worked and had no down sides. Because it’s built in Flash, there are no cross-browser issues. Because it’s modeled after HTML and JavaScript, developers don’t have to be called in for every little change to the widget. For some reason, this has also made the code written in Frontal highly reusable and so there were certain efficiencies gained from having used Frontal on several other projects. And because Frontal is a feature-rich framework, tasks like integrating analytics, submitting forms, handling animated buttons, adding scrollbars, creating linked images and defining section transitions among other things are super easy.
For the backend, we chose PHP and MySQL. This was primarily because it was unclear for a while where the database would be hosted and so we wanted to choose very common technologies that are supported across many platforms.
Our next step was to decide where the widget would be hosted. That is, where would the SWF, image and XML files that make up the widget live? While this choice is not so important as long is it can handle the traffic, what is important is the choice of URL as this will be visible in the widget’s embed code and in the visitor’s browser activity.
Then we began by developing the widget’s basic functionality to be able to sign the petition and search the resulting database.
When we had a working widget, it was time to begin work on the social media integrations. First up was Twitter.
TWITTER INTEGRATION
The Twitter integration was very straightforward. We simply added a link to the widget like so:
http://twitter.com/home?status=Tweet text goes here
In place of “Tweet text goes here” we put the URL-escaped version of the message we wanted to send. For us, the message was “Ignite a National Movement to Inspire Girls w/ @barbiestyle & The White House Project. http://bit.ly/arndS5 #barbiewhp.” To URL-escape the message, we have a tool here that we use: http://basikgroup.com/escape.cgi. After using that, our Twitter share-link looked like this. (We manually replaced spaces with %20 though I don’t think it was necessary.):
http://twitter.com/home?status=Ignite%20a%20National%20Movement%20to%20Inspire%20Girls%20w%2F%20%40barbiestyle%20%26%20The%20White%20House%20Project.%20http%3A%2F%2Fbit.ly%2FarndS5%20%23barbiewhp
Be sure that the target of the link is a blank browser window. (Setting the target is specific to the technology you are using for the widget. For HTML and Frontal it’s a matter of setting the target attribute to “_blank”. For Flash, see the reference for the navigateToURL API for directions.) We do this because when the widget is embedded in Facebook and the target is not set, you may get Flash security errors or silent failures when the visitor clicks the link.
EMAIL INTEGRATION
For the email integration we chose to use a mailto link as opposed to submitting a form to the server that would then turn around and send the requested email. While our approach can be less elegant than the alternative and may simply not work if the visitor hasn’t registered a mail client with their browser, it does have its advantages. Namely, it is more likely to avoid spam filters, it allows for a more personalized message thus increasing the chances that the recipient will act on it, and it doesn’t require submitting an email address to the server which can make some people uneasy.
The basic structure of a mailto link is like so:
mailto:?subject=Subject goes here&body=Message goes here
In place of “Subject goes here” and “Message goes here” we put the URL-escaped texts we want the visitor’s email client to open the new email with. (See the section on Twitter Integration for a discussion of how to URL-escape your message.) To add line breaks in the message, use this string of characters: “%0D%0A”.
For us, the subject we wanted was “Ignite a National Movement to Inspire Girls and Sign the Declaration. I did!” and the message we wanted was:
On April 22nd, we ask The Office of The First Lady of the United States Michelle Obama to accept this Declaration from us powerful girls and women at a proposed ceremony celebrating “Take Our Daughters and Sons to Work Day.” Make sure your voice – and dreams – are heard by signing. I did!
http://bit.ly/arndS5
So our final link looked like this. (Note that the BASIK escape.cgi tool puts “<br>” in for line breaks. We manually replaced those with %0D%0A.):
mailto:?subject=Ignite a National Movement to Inspire Girls and Sign the Declaration. I did%21&body=On April 22nd%2C we ask The Office of The First Lady of the United States Michelle Obama to accept this Declaration from us powerful girls and women at a proposed ceremony celebrating %22Take Our Daughters and Sons to Work Day.%22 Make sure your voice - and dreams - are heard by signing. I did%21%0D%0A%0D%0Ahttp%3A%2F%2Fbit.ly%2FarndS5
Note that when Microsoft Outlook is used to handle this mailto link, there is one blank line at the beginning of the message. We have been unable to come up with a way to remove this.
Finally, as for the Twitter integration, be sure the target of the mailto link is a blank browser window. See the section on the Twitter integration for more details.
FACEBOOK SHARING INTEGRATION
In this case we are talking about what should be the simple task of letting a visitor share a link to their wall. The basic idea is to define a link that looks like the following:
http://www.facebook.com/sharer.php?u=Link goes here&t=Title goes here
In place of “Link goes here” we put the URL-escaped link that we want to share. In place of “Title goes here” we put the URL-escaped title for the link though this is only used temporarily by Facebook as described below. (See the section on Twitter Integration for a discussion of how to URL-escape your message.)
So for us, the link we wanted to share was http://thewhitehouseproject.org/barbie/ and the title was “Ignite a National Movement to Inspire Girls” and so our final link was this:
http://www.facebook.com/sharer.php?u=http%3A%2F%2Fthewhitehouseproject.org%2Fbarbie%2F&t=Ignite%20a%20National%20Movement%20to%20Inspire%20Girls
Now for the complications. When Facebook gets a share link, it opens a share page on its site. It’s this page that lets a visitor login and edit what will actually be shared to their wall.
At first, the share page shows the title you passed in via the share link but shortly thereafter it is updated. What happened? Well, whenever Facebook gets a link to share, its servers actually follow that link and investigate what’s on the other end of it. From this investigation, it updates the title of the shared link and potentially adds an image and a description. It gets this information by looking in the HTML contents at the shared link for these three header tags:
<meta name="title" content="Title goes here" />
<meta name="description" content="Description goes here" />
<link rel="image_src" href="Image link goes here" />
The obvious implications of this are that the HTML of the page whose link you are sharing needs to be edited. Moreover, because you can only put these tags in the HTML once, the link cannot be used for sharing anything else.
A less obvious implication is that Facebook is caching the data it is pulling from the HTML page and so changes you make may or may not be immediately apparent when sharing to Facebook. (For us, we’ve had to wait at most a few hours before the cached was refreshed.)
Another implication is that you cannot share a Facebook page with this mechanism. This is because you can’t embed those necessary HTML tags in the Facebook page you are linking too. Below we’ll discuss how you can share a Facebook page from within Facebook but that doesn’t help us here.
What this last point means is that we cannot use a Facebook URL for the “share to Facebook” link in the widget. This is a disappointing limitation of Facebook.
So, given all of that we ended up using a link to thewhitehouseproject.org for our “share to Facebook” link. And on that page, we added the HTML tags used by the Facebook sharing application. They looked like this:
<meta name="title" content="Ignite a National Movement to Inspire Girls and Sign the Declaration. I did!" />
<meta name="description" content='On April 22nd, we ask The Office of The First Lady of the United States Michelle Obama to accept this Declaration from us powerful girls and women at a proposed ceremony celebrating "Take Our Daughters and Sons to Work Day." Make sure your voice - and dreams - are heard by signing. I did!' />
<link rel="image_src" href="http://social.basikgroup.com/barbie_petition/images/barbie.jpg" />
There was one other issue we had with Facebook sharing which is that for about 24 hours, right after we launched, it stopped working. That is, when the visitor would click on the link to share the widget on Facebook, they would be taken to the Facebook share page. But when they clicked the button to actually share the link, they were shown the error “Something went wrong. We’re working on getting it fixed as soon as we can.” Posting this problem on the Facebook developer’s forum and opening a bug got no response. The only solution we had was to wait.
EMBEDDING THE WIDGET IN HTML OR A BLOG
Next we needed to write the embed code for the widget that can be copied and pasted into a visitor’s HTML page or blog. This is a pretty straightforward task and involves writing a little HTML snippet that can work to embed a Flash movie in a cross-browser compliant way. The basic format is this though in production we recommend removing all of the line breaks shown here for readability.
<object width="" height="">
<param name="movie" value="Movie URL goes here"></param>
<param name="allowscriptaccess" value="always"></param>
<param name="wmode" value="transparent"></param>
<embed src="Movie URL goes here too" type="application/x-shockwave-flash" allowscriptaccess="always" wmode="transparent" width="" height=""></embed>
</object>
So a few things to note. Various sites will munge your embed code before putting the result in the page. MySpace and Blogger come to mind. As a result, do not try to shorten the tags from “<param></param>” to “<param />” as this breaks some parsers. Some sites will change the allowscriptaccess value for the embedding and if that happens, anything that depends on JavaScript access will not work. And if you do not set the wmode to transparent, then the widget will obscure HTML elements that overlap the widget. This is particularly noticeable in Blogger.
Our embed code then was this:
<object width="408" height="508"><param name="movie" value="http://social.basikgroup.com/barbie_petition/frontal_renderer.swf?siteDefnURL=http://social.basikgroup.com/barbie_petition/site.xml"></param><param name="allowscriptaccess" value="always"></param><param name="wmode" value="transparent"></param><embed src="http://social.basikgroup.com/barbie_petition/frontal_renderer.swf?siteDefnURL=http://social.basikgroup.com/barbie_petition/site.xml" type="application/x-shockwave-flash" allowscriptaccess="always" wmode="transparent" width="408" height="508"></embed></object>
EMBEDDING THE WIDGET IN FACEBOOK
The goal here was to embed the widget in a tab of the Barbie Facebook page. First off, this meant that our widget needed to be less than 520 pixels wide.
Next we needed to add the Static FBML application to the page. If the Static FBML application is not already being used on the page then to add it you need to first edit the page. (The link to edit the page is just below the photo on the page’s home.) On the resulting screen, scroll to the bottom and choose “More Applications.” On that screen, type “Static FBML” in the search box. Click the application in the search result set. You will now be on the Static FBML application page. Below its photo will be a link “Add to My Page.” Click that. You should now see your page listed and be able to click it to add the application.
If you do not see your page then either you have not been given administrator permissions or the Static FBML application has already been added to your page. In the former case, get permissions by editing the page. In the latter case, find the Static FBML page already installed on your page and choose to edit it. (This is also done from the edit page.) Near the bottom of the resulting screen will be a link like “add another.” Do this and now you will have a new Static FBML entry listed when you go back and edit the page again.
Now, from the edit page choose to edit the blank Static FBML application. Here you can set a title (we used “Sign the Declaration”) and its contents. The contents can be static HTML as well as FBML markup. For us, we chose to add a share button and the widget.
We chose to add a share button because when using FBML, you can set the share link’s title, description and image directly with the link. This means that from within Facebook we can successfully add a share link to a Facebook URL. (If you’re wondering why I’m so excited by that then please go back and read the section on Facebook sharing integration.)
For us, the contents of our Static FBML application were the following:
<fb:share-button class="meta">
<meta name="medium" content="mult"/>
<meta name="title" content="Ignite a National Movement to Inspire Girls and Sign the Declaration. I did!" />
<meta name="description" content='On April 22nd, we ask The Office of The First Lady of the United States Michelle Obama to accept this Declaration from us powerful girls and women at a proposed ceremony celebrating "Take Our Daughters and Sons to Work Day." Make sure your voice - and dreams - are heard by signing. I did!' />
<link rel="image_src" href="http://social.basikgroup.com/barbie_petition/images/barbie.jpg" />
<link rel="target_url" href="http://bit.ly/arndS5" />
</fb:share-button>
<center>
<fb:swf swfsrc="http://social.basikgroup.com/barbie_petition/frontal_renderer.swf?siteDefnURL=http://social.basikgroup.com/barbie_petition/site.xml" imgsrc="http://social.basikgroup.com/barbie_petition/barbie_facebook_landing.png" width="408" height="508" quality="high" waitforclick="false" swfbgcolor="#ffffff" />
</center>
The last step then is to add this instance of the Static FBML application as a tab to the Facebook page. Go to the Facebook page and click the plus sign at the right end of the tabs. From the dropdown, choose the Static FBML instance we’ve added. That’s it! Now you can drag the tab among the other tabs to position it.
So you can see the result of this by going to http://www.facebook.com/barbie/ and clicking on the “Sign the Declaration” tab. What you will see is a static image that is clickable. Clicking this image removes it and loads the widget. This is a limitation with embedding Flash movies in Facebook and we are unaware of how to change that behavior. (The documentation would seem to say that adding the attribute waitforclick=”false” to the fb:swf tag would have the desired effect but as you can see it does not.) We have no idea why Facebook embeds Flash this way and we wish it wouldn’t.
ADDING ANALYTICS TO THE WIDGET
We made the choice to use Google Analytics for tracking the usage of the widget. The difficulty of this choice is that Google Analytics is primarily a JavaScript-based tool and as a widget we can’t assume that the Google Analytics library has been loaded by our host page or that we would have access to the JavaScript environment if it were. Fortunately there is a Flash library available for just this instance: http://code.google.com/p/gaforflash/. This library allows us to generate page views and events that show up in our Google Analytics account without using JavaScript. We integrated this into our Frontal document which made it very easy to use and allowed us to capture all the information we needed.
One open problem we had was being able to separate page views and events by the host that had embedded the widget. We believe that there might be a solution to this problem but we have not pursued the hypothesis yet.
LAUNCH PLAN
With all the pieces of our widget in place, all that was left was to launch it. Here are the steps we took in our launch plan.
1. We installed a version of the widget at the production URL. This version did not have finalized links for the Facebook, Twitter or email integrations yet.
2. We embedded the widget on The White House Project site at the URL that would be used for Facebook sharing. (This URL was not publicly known yet.) We updated the HTML header tags of that page to support that functionality. We put the URL in the widget’s source code.
3. In the Barbie Facebook page, we created a “Sign the Declaration” tab using the Static FBML application. For its contents we put “Coming Soon!”
4. Now that we had a Facebook URL for the widget, we used bit.ly to create a shortened, trackable link.
5. We then put the bit.ly link in the email integration in the widget’s source code.
6. With the widget source code now edited with the production URLs, we updated it on the production server.
7. We cleaned the petition database of test data.
8. We edited the “Sign the Declaration” Static FBML application on the Facebook Barbie page with the share and widget code.
And with that the widget was live and marketing could begin.
Hello,
As a widget developer that has launched several major brand widgets and as well have approached them differently each time as the landscape is constantly changing under-foot, this is an excellent on-point article. Thanks for introducing me to FRONTAL, I will be very eager to try this out on my next project.
Kudos!
Some questions/comments about your process outlined here:
There are several built-in PHP functions for escaping urls, urlencode(), htmletntities(), htmlspecialchars so you don’t have to manually replace any spaces with %20.
Since the TARGET attribute is deprecated and not valid WC3 XHTML, do you have another proposed method for targeting new browser windows that validates? Will any of the existing Javascript methods for placing click event handlers on all links with rel=”external” for example work within your Frontal framework?
To force Facebook to recognize your shared link as new and so to avoid the content cache, append an html fragment to your link, so “http://example.com/example.html#” . $timestamp() will do nicely to make each link new, or append abs ( timestamp() / 60 * 60 ) to force the cache every hour or more ( 3600 seconds in an hour ).
To share a Facebook page, you probably can use a redirect stub page that exposes the head elements for FB’s RDF of the user-agent string is the Facebook crawler, or redirect the user if not the FB crawler.
I prefer to use validating ‘embed’ code and remove the embed element completely, as it is not WC3 specification, and instead rely solely on the object code, and implement the Satay method for streaming flash content if needed. Excellent that you’ve done away with the codebase attribute to the object tag, but you should really also use a data attribute with the flash url as the value data=”mymovie.swf” and another param “src” element as described here: http://www.alistapart.com/articles/byebyeembed/
Myspace will definitely turn allowscriptaccess=”internal” to prevent any type of javascript and external linking. Workarounds are to make a function which detects this environment and provides alternate visual indicators of external links with the ability for someone to copy and paste links out of the widgets when sandboxed like this. A technique similar to the one used by Widgetbox described here can be homerolled: http://docs.widgetbox.com/developers/guide/flash/
In your mailto: links, change the embedded apresands to html entities and see if Outlook handles the link better, so &subject=mysubjecthere&body=mybodyhere
To get Facebook to load the content properly, there are some additional meta tags to the RDF, adding a link element with rel attribute “video_src” , and meta elements for video_height, video_width, medium (with content=”video” and video_type with content=”application/x-shockwave-flash” may help with your embedding problems.
It’s also best to get the domain serving the content whitelisted by FB by filling out this form: http://www.facebook.com/developers/developer_help.php?category=Video%20Embed
and then, you will know after recieving a response form FB that you have been whitelisted, but check the preview page when you go to share your links, it should have an extra hidden form input element as below, where the “safe” value is equal to “1″ instead of not present or null.
These hints are specific to shared video, but all flash content is “video” content, so it seems a reasonable necessity for flash based widgets.
I am going to start working with gaforflash and see if I can find a solution to your problem of separating the host/widget page hits. I think this should be possible with the correct use of goals and funnels in GA with generated url query params based on the widgets environment.