Custom Stories on the Web
This document describes the key steps to publish your first story with Open Graph.
Before getting started, you'll need to:
- Create a Facebook App ID
- Configure your app to work with Facebook
- Have access to a public web server where you can create one static web page
Once you're done with this guide, you can also learn about possible next steps.
Create a Facebook App ID
You may already have a Facebook App ID for your project. You can use the same App ID across multiple platforms e.g. iOS, Android and a Website.
If you don't already have a Facebook App ID for your project, you first should create one:Create a new App ID
This will create a popup box will prompt you to enter two things:
- A display name. This is the app name used when stories are published to Facebook and in a number of other places. Use Open Graph Getting Started or something similar.
- A namespace. Not required for this guide so just leave it blank.
- A category. This will determine the kind of app that you're building. For now, just select Communication.
Once you've created your app you'll be provided with a dashboard that shows User and API Stats. From this screen, click on Settings on the left.
Complete the following fields, as shown in the screenshot below:
- Contact Email. Your developer email address.
- App Domains. The domain that your app will be hosted on (without the http:// or https:// prefix.)
This example is a basic web page, so you will need to add the web as a platform. Click Add Platform at the bottom of the page and select Website.
Enter a path where you will want to store your file, which will be given to you below.
When you're done, click Save Changes at the bottom.
Set Up the App
Place the following file at the URI you specified in the settings above.
In the file, you need to change one item, which is the App ID. Search for 'fbAppId' in the file and replace its value with the App ID listed at the top of the Settings page in the App Dashboard.
Publish a Story
If you load the app, you should see the following:
Log in, authorize the app to post to your timeline and click the "Create a story..." button. You should see something like this:
You'll note that the result is listed below the button. If you click it, it takes you to the activity that was created on Facebook. It should look something like this:
You should notice a few things about the activity on Facebook:
The light-blue dashed border around the outside indicates that the post is only visible to you. A post visible to friends or public won't have a border, although it will have an icon to replace the lock to indicate how widely it's shared. You can set the privacy of a post with the privacy parameter, included with the demo code. Developers don't usually include a privacy parameter, instead allowing the default privacy of the app to dictate how widely something is shared.
Actions and Objects
The center part of the story is very important. It says that "[subject] likes an article on [app]". The 'likes' was driven by the API that you used.
og.likes creates like stories. If you had used the
book.reads API instead the story probably would have said something like "..is reading..." or "...read... ." The like API, which we call an Action, is roughly the same as a verb.
The "article" part of the story is also very important. The page in question has tags that describe what it is and how it should be displayed on Facebook. If you look at the source for the page you'll see that it contains a tag that tells Facebook what kind of content it is:
<meta property="og:type" content="article" />
This is how Facebook knows that it's an article as opposed to, say, a book.
<meta property="og:type" content="book" />
These tags are what we use to describe Objects. Objects are roughly equivalent to nouns. Objects are closely tied to the Actions you use. For example,
books.reads can take a
fitness.runs requires a
og.likes is special in that it can accept any object.
Submit Your Actions For Review
If your app will be creating stories, then your actions require review. Click on App Review on the left hand side of the App Dashboard and you should see something like this:
Click on Start a Submission and you will see a screen like this:
In Step 3, we talked about how stories were made up of actions and objects. In this case, your story used the
like action, and that's what needs approval. (The App Center approval is there if you want to submit your app to Facebook's app center. The App Center is where people find interesting apps, and is something you should consider to drive distribution of your app when you're ready.)
In order to complete the submission process, you need to provide an app logo (a 75x75px image) and an app icon (16x16px image), instructions on how to test it with screenshots and an automatically created test user. The submission process shouldn't block your ability to test your own changes, since you and anyone else you add as a developer can always post and test your own stories.
If you want to learn more about the submission process, see our Understanding the Open Graph Submission Process document. It gives overall guidance on what Facebook looks for when approving the stories that apps can create. As a smaller example, provide specific guidance about how to use the
like action in your app. We generally complete reviews within three working days.
Actions don't show up in the list for approval until you've used them once from your app. So when you're ready to add your own you're going to need to create at least one action from your app before you can submit it for approval.