Describing history with moments

Great moments in history

Google+ History Logo

In a previous post on Google+ history, I discussed why publishers should pay attention to what is happening with Google+ history and explained what the feature is at a high level. In this post, I will first share a few useful things I did when playing with moments and will look further into the ways that various types of microformats currently render in Google+.

My lazy way of writing moments

First, you might wonder how I am creating moments given that I am testing with various types. Well…. I wrapped the moment API with a simple script that in the general case lets me pass in only two values: the URL for the page, specified in schema.org markup, and the activity type from the Google+ History API documentation. For example, the following JavaScript code uses the wrapper to create an activity with me, specified in markup on wheresgus.com.

<button onClick='writeThisMoment("http://wheresgus.com/history/gus.html","http://schemas.google.com/AddActivity");'>Write This Moment</button>
Of note in the history API, there’s a third value that sometimes needs to get passed, the result object, that specifies targets for an activity.  For example, if you are creating a review, the response object contains information for the thing you are reviewing.

The following code shows how I wrapped the case when a response is necessary:

          "type": "http://schema.org/Review",
          "name": "A Humble Review of Widget",
          "url": "http://wheresgus.com/history/review.html",
          "text": "It is amazingly effective at whatever it is that it is supposed to do.",
          "reviewRating": {
            "type": "http://schema.org/Rating",
            "ratingValue": "100",
            "bestRating": "100",
            "worstRating": "0"
          }
        };
        writeThisMoment("https://developers.google.com/+/plugins/snippet/examples/widget", "http://schemas.google.com/ReviewActivity", theResult);

There are a few things to understand when writing moments with a result associated.  First, the thing being referenced must have valid markup, and second, the thing being referenced must be of appropriate type.  In this case, I was unable to create a review of a review , because the review type is inappropriate for the review result. Finally, most of the example moments pulled from history were created using the Google+ history starter projectmy live Google+ history example can be seen on my example domain if you want to see what the project looks like without having to set it up.

Are there any test Schemas to help me get started?

So you’re chomping at the bit to get started! When you are just beginning, it can be a little tricky determining where bugs exist when you are writing moments.  I have found it helpful to have a few basic test types when you’re debugging, particularly when you’re testing moments.  The following table lists a few types to get you started with writing moments.

SchemaExample targetActivities used in
PersonGusReview
PlaceCharlie’s CafeCheckInActivity, ReserveActivity
ThingA Widget ProductReview, BuyActivity
BlogAn example blog entryCommentActivity
VideoGoogle+ Office HoursViewActivity
Video – MovieIMDB works, e.g. The Matrix (1999)ViewActivity
Video – TV EpisodeIMDB works, e.g. Kyle XY Episode 1 (Pilot)ViewActivity

 

Any gotchas I should be aware of when starting with history?

Everything is CaSe seNsitive.  You will receive the following response error:

Response: : {
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "invalid",
        "message": "Invalid Value"
      }
    ],
    "code": 400,
    "message": "Invalid Value"
  }
}

Your target schema must be valid and complete for the activity.  Use the MicroBeta Chrome Extension to validate your schema objects.

Which moment do I use and how do they currently look in history?

BuyActivity

Google+ History Buy

The buy activity is used whenever the user purchases something.  For example, a developer could write one of these moments as part of the checkout process for an e-commerce site or even if you are an independent comedian who is distributing her content online, this activity would be appropriate when a user purchases your movie or show.

CheckInActivity

Google+ History Check-in

The checkin activity is used whenever the user checks into a venue, landmark, and so forth.  For example, let’s say that a user is in a restaurant and your app or web service tracks whenever a user claims to be somewhere, this activity would be appropriate.

CommentActivity

Google+ History Comment

This activity is used whenever a user comments on a post, blog, or article.  For example, let’s say that the user has made a comment using a comment service, the service itself could write moments to Google+ history for the comments.  As another example, let’s say you use blogging software that supports comments, you could add support for moments whenever a user posts to the blog.  For the user, this is useful because they would remember where they commented, for you as a blogger, you could get hooks from Google+ back into your blog to further drive discussions.

CreateActivity

Google+ Create Activity

The create activity should be used whenever a user publishes a creative work.  For example, let’s say that you have a product that lets a user produce those awesome viral pictures, whenever a user creates a new meme,  a moment could be created to a user’s history line letting them share it easily with their social circles.

ListenActivity

Google+ History Listen

The listen activity should be used when a user listens to a song, album, or artist.  For example, if you have a radio station with an online presence, you could write the songs played by the DJ to a user’s history while they listen so that the users would have a record of the radio station’s playlist.

ReserveActivity

Google+ History Reservation

The reserve activity is used whenever a user makes a reservation at a local business.  This is useful for products that allow users to make reservations.  For example, let’s say a user makes a reservation for their birthday party at a little known local business.  They could use the moment from their history to share out the venue to their friends.

ReviewActivity

Google+ History Review

The review activity is used for reviewing things.  Let’s say you have an e-commerce site that supports reviews, whenever a user reviews something, you could write their review data to history.

ViewActivity – video

Google+ History video view

This activity should be used when a user watches a video.  For example, if you have a viral video site, this activity could be used to track the videos watched and to make it easy for users to share watched videos on Google+. Another example could be appropriate to video players, rather than store a history of videos watched in the player itself, you could write these plays back to a user’s timeline.

ViewActivity – movie

An example of how movies look in Google+ history

This activity is for when a user watches a movie. If you had a streaming movie service, for example, you could help users track the movies they watched by writing view activities to their history.

ViewActivity – TV episode

An example of how TV views appear in Google+ History

This activity is for when a user watches a tv episode.  For example, if you are a television station and let users watch your shows online, you could write moments to a user’s history that let them share and remember the shows they have watched, or which episode they are on.

AddActivity

Google+ History Add

Finally, what if I have an activity that doesn’t have an appropriate moment yet? For these moments, the ones we don’t yet support, use the AddActivity type.  This moment is used when no other appropriate moment exists.  For example, let’s say that you want a moment to represent completing a workout for an exercise activity, you would use the AddActivity moment.

Summary and cheatsheet

So that’s pretty much it for moments, I have created a Google+ moment cheatsheetso you can have a quick summary of moments – the following is an abbreviated version.

MomentWhen to useTypeSchema TargetUses Result*
AddActivityNo other appropriate activityAddActivitything
BuyActivityUser purchaes somethingBuyActivitything
CheckInActivityUser checks into a placeCheckInActivityPlace
CommentActivityUser comments on a creative workCommentActivityCreativeWork
CreateActivityUser made a creative workCreateActivityCreativeWork
ListenActivityUser listens to a songListenActivityMusicRecording
ReserveActivityUsers makes a reservation at a local businessReserveActivityLocalBusiness
ReviewActivityUser writes a review of somethingReviewActivityReviewActivity
ViewActivity – videoUser views a videoViewActivityVideoObject
ViewActivity – movieUser views a movieViewActivityMovie
ViewActivity – TV episodeUser views a TV episodeViewActivityTVEpisode

* Indicates that result should be passed to the API.

For further discussion

I still haven’t even breached the topic of what is the right way to share and how publishers should think about the metadata they share in markup.  Maybe I will address this in a future post, but this will change as the supported activities change.  In general, mark up your content with as accurate a schema as possible, try and use the right activity when you share, and that is the best you can do.

See Also