Tutorial: Eigene „Running“ Timeline Anwendung erstellen (beta)

Tutorial: Eigene „Running“ Timeline Anwendung erstellen (beta)


[English translation: see below]

Passend zu unserem Artikel über die Nike+ GPS App haben wir ein Tutorial erstellt, wie ihr eine Anwendung mit Kartenfunktion in der Timeline erstellt werden kann. Leider deckt die offizielle Dokumentation diesen Punkt nicht ab, mit dem entsprechenden Know-How und Übung ist die Struktur in 5-15 Minuten eingerichtet (Anfänger dürften ggf. etwas länger brauchen). Bevor man dieses Tutorial angeht, sollte man auf jeden Fall die grundlegende Einführung zur Erstellung von Aktionen und Objekten durchgehen und ausprobieren! Des weiteren sollte man beachten, dass die Zusammenfassungen (Aggregations) und Darstellungen der Aktionen noch immer im Beta Status sind. Es können trotzdem bereits nahezu vollständig funktionierende Anwendungen vorbereitet werden. Sobald sich etwas neues ergibt, werden wir an dieser Stelle natürlich darüber berichten.

Objekt mit Route erstellen

Für die Erstellung von Kartenansichten in der Timeline steht der Datentyp „GeoPoint“ zur Verfügung. Dieser Array besteht aus den Werten „latitude“, longitude“ und „altitude“. Zweck von Latitude und Longitude erklären sich von selbst, die Höhenangabe (altitude) hat bisher keine Verwendung. Da es den GeoPoint in den Open Graph Aktionen (noch) nicht als Datentyp existiert, müssen alle positions- und streckenbezogenen Daten in ein Open Graph Objekt gelegt werden.

Somit muss zunächst ein Objekt angelegt werden, wir haben dieses „Run“ genannt um einen Lauf oder eine Rennstrecke darzustellen. Dem Objekt geben wir folgende Eigenschaften:

  • Route: Diese Eigenschaft vom Datentyp GeoPoint stellt unsere Route dar, d.h. eine Sammlung aus GeoPositionsangaben. Um keinen einzelnen Punkt sondern eine Menge darzustellen, muss die Eigenschaft als „Is Array“ angelegt werden. Dies ist das einfache Geheimnis wie wir zur Route kommen, die Formatierung der OG Meta Properties folgt später im Artikel.
  • StartPoint / EndPoint: Da dem Datentyp GeoPoint keine weitere Eigenschaften als dessen Position gegeben werden können, fügen wir zwei weitere Punkte vom Typ GeoPoint hinzu und nennen diese bspweise „StartPoint“ bzw. „EndPoint“. Diese Eigenschaften sind KEIN Array und dienen zur Markierung von Streckenbeginn und Streckenende.

Weitere Werte (optional):

  • HighestPoint: Um besondere Punkte auf der Karte hervorzuheben können weitere Punkte hinzugefügt werden. Es bietet sich an beispielsweise den höchsten Punkt hervorzuheben.
  • Distance: Die zurückgelegte Strecke wird nicht automatisch berechnet. Daher diese mit dem Datentyp „Quantity“ hinzufügen. Quantity ermöglicht es einem Zahlenwert zusätzlich eine Einheit zuzuweisen. Die Möglichen Einheiten können beim Eintragen der Beispielwerte („Edit Sample Values“) eingesehen werden.
  • Duration: Ein weiterer Wert, der ebenfalls bereits jetzt angelegt werden kann, jedoch noch nicht verwendet wird, wäre die Streckenzeit (nicht im Screenshot). Diese als Integer in Sekunden angeben. D.h. wenn der Lauf eine Stunde dauerte, müsste der Wert „3600“ sein.

 

Zusätzlich können weitere Werte wie die Durchschnittsgeschwindigkeit hinzugefügt werden. In der Timeline können pro Aktion – neben der Strecke – maximal drei Werte des Objekts als Überschriften/Labels angezeigt werden.

Aktion erstellen

Im Anschluss erstellen wir die passende Aktion, die wir ebenfalls „Run“ genannt haben. „Run a Run“ hört sich erstmal nicht so gut wie „Read a Book“ an, das soll nun aber mal nicht unser Hauptproblem sein. Die „run“ Aktion wird mit dem „run“ Objekt verknüpft. Weiteres muss bei den grundlegenden Einstellungen nicht beachtet werden.

Entscheidend ist das Attachment Layout. Hier den Typ auf „Map“ stellen.Im Punkt Numbers können wir bis zu drei Referenzen auf das „Run“ Objekt vergeben. Hierzu mit dem Syntax OBJEKTNAME.EIGENSCHAFT (Beispiel: run.distance) vorgehen und einen Titel sowie Mengeneinheit festlegen. Je nach Datenformat lassen sich Zahlenwerte automatisch formatieren. Um beispielsweise Zeiteinheiten zu formatieren wird der Formatter „duration“ verwendet: {run.duration | duration}. Der Zahlenwert wird in folgendes Format umgewandelt: {hours}:{minutes}:{seconds} oder {minutes}:{seconds} falls keine Stunden verfügbar sind. Ein Datum kann über die php date() Funktion formatiert werden. Beispiel: {time | date(“M d, Y”)} => Aug 10, 2011. Besonderes Gimmick: Verwendet man date(„fb_relative“) als Parameter erscheint ein relativer Zeitwert wie bspweise „One week ago„.

In Highlighted Points darf natürlich nicht die Route, sondern die zuvor angelegten Positionen StartPoint, EndPoint und opt. HighestPoint eingetragen werden. Abschließend in „Route“ unseren GeoPoint-Array „run.route“ eintragen.

OG Meta Properties exportieren
Mit Klick auf „Code erhalten“ (in der rechten Spalte des „run“ Objekts) generiert die Konsole automatisch die (fast) vollständige OG Meta Properties Struktur. Hier ist zu beachten, dass nicht alle Werte angezeigt werden, wenn keine Beispielwerte eingetragen wurden! Der Export könnte bspweise folgendes Ergebnis ausliefern:

<head prefix="og: http://ogp.me/ns# fb: http://ogp.me/ns/fb# CANVASNAME: http://ogp.me/ns/fb/CANVASNAME#">
<meta property="fb:app_id"                        content="APP_ID" />
<meta property="og:type"                          content="CANVASNAME:run" />
<meta property="og:url"                           content="http://Put_Your_Own_URL_Here.com/object_id" />
<meta property="og:title"                         content="Sample Run" />
<meta property="og:description"                   content="Some Arbitrary String" />
<meta property="og:image"                         content="https://s-static.ak.fbcdn.net/images/devsite/attachment_blank.png" />
<meta property="CANVASNAME:route:latitude"         content="48.896324" />
<meta property="CANVASNAME:route:longitude"        content="9.169092" />
<meta property="CANVASNAME:route:altitude"         content="300" />
<meta property="CANVASNAME:startpoint:latitude"    content="48.896324" />
<meta property="CANVASNAME:startpoint:longitude"   content="9.169092" />
<meta property="CANVASNAME:startpoint:altitude"    content="300" />
<meta property="CANVASNAME:endpoint:latitude"      content="48.893503" />
<meta property="CANVASNAME:endpoint:longitude"     content="9.180593" />
<meta property="CANVASNAME:endpoint:altitude"      content="320" />
<meta property="CANVASNAME:highestpoint:latitude"  content="48.88515" />
<meta property="CANVASNAME:highestpoint:longitude" content="9.150724" />
<meta property="CANVASNAME:highestpoint:altitude"  content="350" />
<meta property="CANVASNAME:distance"               content="3.1" />
<meta property="CANVASNAME:distance:units"         content="km" />

CANVASNAME und APP_ID entsprechenden den Werten eurer Anwendung.

Route in OG Meta Properties darstellen
Nun lüften wir das Geheimnis: In welchem Format wird eine Route dargestellt? Auch eine einfach Antwort: Durch Wiederholung der Werte und selber Bezeichnung. Dies entspricht dem OG Standard zur Darstellung von Arrays. D.h. für unseren Fall, es werden die Werte Latitude, Longitude und Altitude pro Position nacheinander ausgegeben. Das erste Vorkommen entspricht dem ersten Punkt der Route, usw. Hier ein Beispiel:

<meta property="CANVASNAME:route:latitude"  content="48.896324" />
<meta property="CANVASNAME:route:longitude" content="9.169092" />
<meta property="CANVASNAME:route:altitude"  content="310" />
<meta property="CANVASNAME:route:latitude"  content="48.892712" />
<meta property="CANVASNAME:route:longitude" content="9.1751" />
<meta property="CANVASNAME:route:altitude"  content="310" />
<meta property="CANVASNAME:route:latitude"  content="48.893503" />
<meta property="CANVASNAME:route:longitude" content="9.180593" />
<meta property="CANVASNAME:route:altitude"  content="310" />
<meta property="CANVASNAME:route:latitude"  content="48.893503" />
<meta property="CANVASNAME:route:longitude" content="9.180593" />
<meta property="CANVASNAME:route:altitude"  content="310" />
<meta property="CANVASNAME:route:latitude"  content="48.889552" />
<meta property="CANVASNAME:route:longitude" content="9.188318" />
<meta property="CANVASNAME:route:altitude"  content="310" />
<meta property="CANVASNAME:route:latitude"  content="48.889552" />
<meta property="CANVASNAME:route:longitude" content="9.188318" />
<meta property="CANVASNAME:route:altitude"  content="310" />

 

Objekt Struktur testen

Bevor man die Aktion ausführt sollte man sein Objekt zunächst über das Facebook Debug Tool testen. Dies erspart viel Zeit und Ärger! Wenn alles richtig funktioniert hat, sollte man bei der Route einen Array mit der Länge X erhalten (Beispiel siehe Screenshot). Für die „Highlighted Points“ sollten weitere ähnliche einzeilige Einträge vorhanden sein. Für den Fall, dass eure Objekt-Struktur nicht mit den OG Meta Daten übereinstimmt, wird das Tool euch darauf hinweisen. Eure Meta Daten sollten 1:1 der Konfiguration im Facebook Developer-Admin entsprechen. Ansonsten gibt’s selbstverständlich Probleme.

 

Aktion ausführen

Da alle Eigenschaften des Laufs im Objekt definiert wurden, reicht ein einzelner Parameter um die Aktion auszulösen:

<script>
FB.api('/me/CANVASNAME:run?run=http://Put_Your_Own_URL_Here.com/object_id','post', function(response) {
console.log(response);
if (!response || response.error) {
alert('Error occured');
} else {
alert('Post was successful! Action ID: ' + response.id);
}
});
</script>

 

Tadaa! Das Endergebnis…

Über das Aktivitätenprotokoll oder die URL http://www.facebook.com/USERNAME/activity/ACTION_ID kann die erstelle Aktion abgerufen werden. Die „ACTION ID“ erhaltet ihr als Response Wert der Facbeook API Calls. Per Klick auf die Karte erscheint diese (mit Zoom-Optionen und Route) in einer Großansicht. Das Attachment entspricht noch nicht 1:1 der Vorschau in den Settings, ein Fix sollte in den nächsten Tagen bzw. Wochen jedoch folgen. Die Zusammenfassungen sind im Moment (bzw. weiterhin) ebenfalls fehlerhaft. Sobald diese vollständig und stabil laufen, folgt ein Update.

Viel Spaß beim Testen. Ihr könnt gerne Beispiel-Anwendungen/Ergebnisse einsenden.

 

English translation:

Tutorial: Build your own „Running“ Timeline App (beta)

Fitting our article about the Nike+ GPS App we created a tutorial how to build an application offering a timeline maps feature. Unfortunately the official documentation doesn’t cover this point of the OG, however with some know-how and practicing you can create the needed structure within 5-15 minutes (… will take more time for beginners). Prior to starting this tutorial you should read and try-out the basic documenation about building actions and objects. Furthermore you should keep in mind that attachment layouts and aggregations are still in beta. Nevertheless you are able to create a „close-to-running“ application (what a play on words :-). Needless to say, as soon as we get new information about this topic, we’ll report about it here.

Creating an object including a route

For building a map view inside the timeline the Facebook app settings provied the data-type „GeoPoint“. This array is defined by the values „latitude“, longitude“ and „altitude“. There should be no need to explain the intended purpose of latitude and longitude – the option altitude isn’t in use at the moment. As the GeoPoint type doesn’t (yet) exist for open graph actions all position- and route-related information has to be stored inside the open graph object.

Consequently first we need to create an object representing our course, racetrack or route. In our showcase we named it „run“. Assign the following options to the „run“ object:

  • Route: This attribute is representing a collection of positions. It owns the datatype „GeoPoint“. Next – as we don’t want to display a single point but a route – you need to set the option „Is array“. That’s the major step for building our route. The formatting of OG meta properties will be explained later in this article.
  • StartPoint / EndPoint: As it’s not possible to assign further properties (than lat./lon./alt.) append two additional GeoPoint attributes and name them – for example – „StartPoint“ and „EndPoint“. These attributes are NO array! Their propse is marking the beginning and ending of our route.

More attributes (optional):

  • HighestPoint: For highlighting more interesting points on the map you can add more GeoPoint attributes. The highest point of a route would be an example. At the moment it’s not possible to label this marker.
  • Distance: The covered distance won’t be calculated based on the route. Thus add an attribute having the type „Quantity“. „Quantity“ gives your the opportunity to set a numerical value and assign an unit to it. You can review the available units during setting your sample values („Edit Sample Values“).
  • Duration: Another attribute – you already can add now, but it isn’t in use yet – is the duration of the run. The value should be given in seconds as integer. Simple example: If your run takes one hour, the value must be „3600“.

 

In addition you can add even more attributes like the average speed. In your timeline attachment you will be able to display – beside the map itself – up to three values labeling your route.

Create the action

Following create the matching action. We called it „run“, too. „Run a run“ doesn’t sound as well as „Read a Book“ – but this shouldn’t be our main issue. Connect the „run“ action with  the „run“ object. At this point there is no need to take a deeper look at the additonal action settings.

Key factor is the attachment layout. Select the type „map“. Using „numbers“ you can set up to three references to the run object (as previously explained). For this go ahead using the syntax OBJECTNAME.PROPERTYNAME (example: run.distance), set a label and – if needed – an unit or something similar. Depending on your input you can yield the formatting of your values to the attachment generator. For example if you want to format a duration just use the formatter „duration“: {run.duration | duration}. Your value will be converted to {hours}:{minutes}:{seconds} – or {minutes}:{seconds} if there is no hour present. For formatting a date us the php date() function. Example: {time | date(“M d, Y”)} => Aug 10, 2011. Special gimmick: By using date(„fb_relative“) as argument a relative time like „One week ago“ will be displayed.

Next: Don’t insert your route in the field Highlighted Points! Instead use the previously defined single GeoPoints StartPoint, EndPoint and opt. HighestPoint. Closing enter the GeoPoint-array name „run.route“ to the field „Route“.

Export OG meta properties

By clicking the „Get code“ link (inside the right column of the „run“ object) you will receive the (nearly) complete OG meta properties structure. Take care: you won’t get all values/properties if you don’t fill out your example values! A full-fledged export would look like this:

<head prefix="og: http://ogp.me/ns# fb: http://ogp.me/ns/fb# CANVASNAME: http://ogp.me/ns/fb/CANVASNAME#">
<meta property="fb:app_id"                        content="APP_ID" />
<meta property="og:type"                          content="CANVASNAME:run" />
<meta property="og:url"                           content="http://Put_Your_Own_URL_Here.com/object_id" />
<meta property="og:title"                         content="Sample Run" />
<meta property="og:description"                   content="Some Arbitrary String" />
<meta property="og:image"                         content="https://s-static.ak.fbcdn.net/images/devsite/attachment_blank.png" />
<meta property="CANVASNAME:route:latitude"         content="48.896324" />
<meta property="CANVASNAME:route:longitude"        content="9.169092" />
<meta property="CANVASNAME:route:altitude"         content="300" />
<meta property="CANVASNAME:startpoint:latitude"    content="48.896324" />
<meta property="CANVASNAME:startpoint:longitude"   content="9.169092" />
<meta property="CANVASNAME:startpoint:altitude"    content="300" />
<meta property="CANVASNAME:endpoint:latitude"      content="48.893503" />
<meta property="CANVASNAME:endpoint:longitude"     content="9.180593" />
<meta property="CANVASNAME:endpoint:altitude"      content="320" />
<meta property="CANVASNAME:highestpoint:latitude"  content="48.88515" />
<meta property="CANVASNAME:highestpoint:longitude" content="9.150724" />
<meta property="CANVASNAME:highestpoint:altitude"  content="350" />
<meta property="CANVASNAME:distance"               content="3.1" />
<meta property="CANVASNAME:distance:units"         content="km" />

CANVASNAME and APP_ID will be replaced by your app’s values.

Describe a route using OG meta properties
Finally the missing part: Which format do I have to use to describe a route? In the same way as before, simple answer: By repeating your properties using the same notation. This is just the way arrays are displayed according to the OG standard. Which means for our case that latitude, longitude and altitude would be displayed one after another for each position. The first entry is corresponding to the first point of the route, etc. Example:

<meta property="CANVASNAME:route:latitude"  content="48.896324" />
<meta property="CANVASNAME:route:longitude" content="9.169092" />
<meta property="CANVASNAME:route:altitude"  content="310" />
<meta property="CANVASNAME:route:latitude"  content="48.892712" />
<meta property="CANVASNAME:route:longitude" content="9.1751" />
<meta property="CANVASNAME:route:altitude"  content="310" />
<meta property="CANVASNAME:route:latitude"  content="48.893503" />
<meta property="CANVASNAME:route:longitude" content="9.180593" />
<meta property="CANVASNAME:route:altitude"  content="310" />
<meta property="CANVASNAME:route:latitude"  content="48.893503" />
<meta property="CANVASNAME:route:longitude" content="9.180593" />
<meta property="CANVASNAME:route:altitude"  content="310" />
<meta property="CANVASNAME:route:latitude"  content="48.889552" />
<meta property="CANVASNAME:route:longitude" content="9.188318" />
<meta property="CANVASNAME:route:altitude"  content="310" />
<meta property="CANVASNAME:route:latitude"  content="48.889552" />
<meta property="CANVASNAME:route:longitude" content="9.188318" />
<meta property="CANVASNAME:route:altitude"  content="310" />

 

Debug your object structure

 

Now, first of all, you should debug your object using the Facebook Debug Tool. After validating your object, start testing. This is saving time and trouble. If everything is working fine the debugger should display an array next to your „route“ property. Just as well there should be a single array display for each of your highlighting points. For the case your OG meta properties based object structure isn’t matching your app settings, the debug tool will print according error messages: Your meta properties should fit one-to-one to your facebook developer app settings. Otherwise you will be in trouble ;-)

 

Execute your action

As all of our options are defined inside the „run“ object, we only need to pass a single parameter to the post request for executing the „run“ action:

<script>
FB.api('/me/CANVASNAME:run?run=http://Put_Your_Own_URL_Here.com/object_id','post', function(response) {
console.log(response);
if (!response || response.error) {
alert('Error occured');
} else {
alert('Post was successful! Action ID: ' + response.id);
}
});
</script>

 

Tadaa! The final result…

Using the activity protocol or the URL http://www.facebook.com/USERNAME/activity/ACTION_ID you can review the action which just has been created by yourself. You will receive the „ACTION ID“ as response value of your API call. By clicking the map a big interactive map will be opened as a classic-facebook-style overlay (including zoom and move). The attachment doesn’t represent the preview layout in your settings form 1:1, there should be an update for this within the next days or weeks. The aggregations are erroneous, too. As soon as they will run stable, we’ll update this tutorial.

 

Happy testing! Please send in your test results.

Share on FacebookTweet about this on TwitterShare on Google+Pin on PinterestShare on LinkedInBuffer this pageEmail this to someone
Veröffentlichung 30. Januar 2012

+ Es gibt keine Kommentare

Deinen hinzufügen