Describing history with moments
Great moments in history
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>
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 project – my 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.
Schema | Example target | Activities used in |
---|---|---|
Person | Gus | Review |
Place | Charlie’s Cafe | CheckInActivity, ReserveActivity |
Thing | A Widget Product | Review, BuyActivity |
Blog | An example blog entry | CommentActivity |
Video | Google+ Office Hours | ViewActivity |
Video – Movie | IMDB works, e.g. The Matrix (1999) | ViewActivity |
Video – TV Episode | IMDB 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
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
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
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
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
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
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
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
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
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
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
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.
Moment | When to use | Type | Schema Target | Uses Result* |
---|---|---|---|---|
AddActivity | No other appropriate activity | AddActivity | thing | |
BuyActivity | User purchaes something | BuyActivity | thing | |
CheckInActivity | User checks into a place | CheckInActivity | Place | |
CommentActivity | User comments on a creative work | CommentActivity | CreativeWork | |
CreateActivity | User made a creative work | CreateActivity | CreativeWork | ✓ |
ListenActivity | User listens to a song | ListenActivity | MusicRecording | |
ReserveActivity | Users makes a reservation at a local business | ReserveActivity | LocalBusiness | ✓ |
ReviewActivity | User writes a review of something | ReviewActivity | ReviewActivity | ✓ |
ViewActivity – video | User views a video | ViewActivity | VideoObject | |
ViewActivity – movie | User views a movie | ViewActivity | Movie | |
ViewActivity – TV episode | User views a TV episode | ViewActivity | TVEpisode |
* 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.