CuteOn.Me Sample Application

CuteOn.Me is a simple app to solicit shopping advice from your friends. It was built using the awe.sm APIs. No database required!

Try It Now! Download Source on GitHub

How It Works

CuteOn.Me is a web application designed for the simple task of capturing friends' advice about something you're thinking about buying. Using the awe.sm APIs, you can accomplish this with a few tasks:

  • Create unique awe.sm links to send to each friend
  • Update awe.sm links with post-share information
  • Redirect friends to a voting page
  • Capture their votes
  • Display how your friends voted

Create awe.sm links to share

Let's first look at how you create a single awe.sm link and then how you can optimize your API calls using the batch create endpoint.

To capture each friend's opinion, we need a way to differentiate one friend from another. To do this, we can create a unique awe.sm link for each friend.

Share with metadata

For this application, the destination URL will be the webpage we want our friends to vote on. We'll also include additional information which we can utilize later:

  • url = the URL of the webpage we want our friends to vote on
  • user_id = your Twitter user ID so we can identify awe.sm links you created
  • tag = the Twitter user ID of the friend we are sharing to
  • notes = the message we want to include in the Twitter direct message
  • user_id_username = your Twitter username
  • user_id_icon_url = your Twitter user icon url
  • tool = the tool used to create the awe.sm link
  • channel = the social media channel the link is shared to

POST http://api.awe.sm/url.json?v=3&key=103dbc7485b55313c91aa29176f8ee2ba3e95fe949c574aa5f2505e26a5bb743&url=http://www.cuteon.me&user_id=17301118&tag=190498288¬es=cute%20on%20me%20right%3F&user_id_username=bhiles&user_id_icon_url=http://a0.twimg.com/profile_images/1292259951/f_ing_social_media_head_normal.jpg&tool=tHSSFr&channel=twitter-message

{ 
    "awesm_url": "http://CuteOn.Me/2W",
    "awesm_id": "CuteOn.Me_2W",
    "domain": "CuteOn.Me",
    "path": "2W",
    "created_at": "2011-09-26T23:17:47Z",
    "original_url": "http://www.cuteon.me",
    "redirect_url": "http://www.cuteon.me/opinion.php?awesm=CuteOn.Me_2W&sharer_icon_url=&url=http%3A%2F%2Fwww.cuteon.me&message=cute+on+me+right%3F&sharer=bhiles",
    "channel": "twitter-message",
    "service": "twitter",
    "tool": "hackdisrupttool-twitterdm",
    "application": "hackdisrupttool",
    "parent": null,
    "sharer_id": null,
    "username": "bhiles",
    "service_userid": null,
    "service_postid": null,
    "service_postid_metadata": {
        "reach": null,
        "shared_at": null
    },
    "campaign": null,
    "campaign_metadata": {
        "description": null,
        "name": null
    },
    "user_id": "17301118",
    "user_id_metadata": {
        "profile_url": null,
        "icon_url": null
    },
    "tag": "190498288",
    "notes": "cute on me right?"
}

Create API documentation

Create multiple awe.sm links at once

Instead of making an API call to create an awe.sm link for each friend, we can use the batch create endpoint to return multiple awe.sm links with a single API call. If our friends had user IDs 190498288 and 371635480, the API call would be:

POST http://api.awe.sm/url/batch.json?v=3&key=103dbc7485b55313c91aa29176f8ee2ba3e95fe949c574aa5f2505e26a5bb743&url=http://www.cuteon.me&user_id=17301118¬es=cute%20on%20me%20right%3F&user_id_username=bhiles&user_id_icon_url=http://a0.twimg.com/profile_images/1292259951/f_ing_social_media_head_normal.jpg&tool=tHSSFr&channel=twitter-message&tag[]=190498288&tag[]=371635480

Batch create endpoint documentation

Domain names

awe.sm links by default use the domain awe.sm, but can be customized to use your own domain. For this application we use the domain CuteOn.Me.

Custom domain documentation

Sharing with friends

For each of your friends to see the webpage you want their advice on, you need to send each friend the awe.sm link that was created specifically for them. CuteOn.Me uses Twitter direct messages for sharing. So we need to extract the awe.sm link from the Create APIs response and include it in a direct message to each friend.

Updating awe.sm links with data from Twitter

Some information can only be obtained after you share a link, like the exact time of when you shared or the tweet ID. awe.sm links have specific fields for this kind of information. We send direct messages using the Twitter API. After you send a direct message, the API response includes metadata about the post which can be added to the awe.sm link using the update endpoint.

  • service_postid = the ID of the direct message
  • service_postid_shared_at = the time the awe.sm link was shared
  • service_postid_reach = how many people will see your post

Update endpoint documentation

Redirection Patterns

Your friends will receive a direct message containing an awe.sm link. The default configuration for awe.sm links will have it redirect to the URL specified. But, we want to display the URL and capture a vote from the friend. We can use JavaScript to capture the friend's vote, but since the URL could be anything, we won't be able to have JavaScript running on every URL. Instead, we can redirect the friend back to a page we host. Then we can display the URL using an iframe and easily run JavaScript on the page to capture the vote. awe.sm has a feature called redirection patterns where any of an awe.sm link's fields can be used to build the URL that a user is redirected to. Our redirect pattern needs the following logic:

  • Redirect to http://www.cuteon.me/ so we can run JavaScript on the page
  • Include fields:
    • url to view the URL in an iframe
    • awesm_id to attribute a vote to an awe.sm link which has the user ID of the friend

Redirection pattern documentation

We use additional fields in the redirection pattern, so when a friend is redirected they get information about who shared the link to them and the message from the direct message.

The actual redirection pattern is:

http://www.cuteon.me/opinion.php?url=%escaped_original_url%&sharer=%user_id_username%&sharer_icon_url=%user_id_icon_url%&message=%notes%&awesm=%awesm_id%

Track votes with conversions

Once a friend follows the awe.sm link they can make their voting choice. awe.sm links so far have data associated with them, but when a user interacts with a link events are collected. One type of event is a click. When a user clicks on a link, awe.sm captures that a click occurred. Another type of event is conversions, which allow you to capture user-defined actions. The actions we want to collect is whether a friend votes yes or no for the URL displayed. awe.sm supports ten different conversion types per project, so CuteOn.Me uses the first conversion type to be a yes vote, and the second type to be for a no vote. Conversions are collected by calling the Conversions API specifying the awe.sm link, the conversion type, and the value. We have a JavaScript library that takes care of the heavy lifting, so your code just needs to include the library and use a JavaScript trigger to execute.

<script src="http://ywidgets.awe.sm/v3/widgets.js?key=103dbc7485b55313c91aa29176f8ee2ba3e95fe949c574aa5f2505e26a5bb743"></script>
<script>
    function voteYes() { AWESM.convert('goal_1',0); }
    function voteNo() { AWESM.convert('goal_2',0); }
</script>

Conversion documentation

Stats

To show you what your friends voted, we need to query awe.sm for your data. The awe.sm Stats API allows you to query data you created and collected inside awe.sm. We want to group by the URLs you shared, and group again by the friends you shared with so we can see how each friend voted. This translates to a Stats API call filtered by your user_id, grouped by original_url, and then pivoted by tag. We also want to see conversion data which needs to be enabled in the call. Finally, we sort by shared_at so we can see the URL shared most recently first.

POST http://api.awe.sm/stats/range.json?v=3&key=103dbc7485b55313c91aa29176f8ee2ba3e95fe949c574aa5f2505e26a5bb743&user_id=17301118&group_by=original_url&pivot=tag&with_metadata=true&with_conversions=true&sort_type=shared_at

Stats API documentation

The response only shows raw data, so conversions are only displayed as having numeric values. There is no logic in the API call that says what a friend voted, instead we need to create an algorithm to transform the voting conversion data into what a friend voted. The algorithm is:

if goal_1 (yes conversion type) count > 0, then vote is a yes
else if goal_2 (no conversion type) count > 0, then vote is no
else didn't vote

The Stats API call allows us to populate the majority of the dashboard. We can iterate over each URL that was shared, find each of the friends the URL was shared to, and calculate each friends' vote. To make the dashboard more helpful we include additional data. The title of the URL is displayed to allow for a human readable value for the URL. Also, the message that was sent along with the link is displayed. All of this collected using Stats API calls.

Bonus Features

In the CuteOn.Me GitHub repository, there are two branches. The live site uses the performance branch, which contains additional features like the Google Chrome extension, Embedly item previews, and asynchronous Twitter friend lists. As these features complicate the code, we recommend reviewing the master branch first.

Last updated 2012-05-14