The Definitive User's Guide

Finally! Some Documentation! (This is a work-in-progress)

Overview
A few quick notes. Screens or pages in a webOS app are referred to as “scenes” so I will refer to them as such throughout the guide. A scene is basically a new screen/view within the app. The magenta button is the magenta colored button on the upper right of a scene that is captioned with the current view and has a small triangle next to it. The zBar or nav bar is the collection of icons across the bottom of the screen. The Application Menu is the menu in the upper left corner of the screen that says “Foursquare”.

Getting Started
Once you have the app on your device (either from the App Catalog or here on GitHub) and run it, you’ll be asked for a username and password. This is your Foursquare account info. If you don’t have one, tap the sign up link in the app. Once you have an account, enter your e-mail address or phone number and your password and tap Login. If all goes well, you’ll see your information at the bottom of the screen and you’ll be brought to the Nearby Venues scene.

Nearby Venues
The app grabs your GPS position and queries foursquare for venues nearest you. You’ll be greeted with the 25 closest venues. If you want to see more, you can adjust this in the Preferences dialog. (Covered later) If you don’t see the venue you want, you can try searching for it. Tap the magenta button and select Search. This will open a drawer contain a text field and a button. Type the name of the venue into the text field and tap Search. If your venue is found, it’ll be displayed on the screen. If your search still didn’t find the venue, you may need to add it to foursquare. Tap the magenta button and select Add Venue. The app will attempt to find your current city and zipcode and fill these fields in for you. Fill in the remainder of the information and click Add. If it went well, the Venue Detail scene will be displayed, showing the venue you just added.

If you want to get a new list of venues if, say, you’ve changed positions, you can tap the application menu and select Refresh.

If you didn’t add a venue, tap one from the Nearby list, or from the search results. This will display the Venue Detail scene. From here you can see a small map of the area, the mayor of the venue, nearby specials, tips, and contact information for the venue. You can also propose edits to the venue and flag it as being closed if it is.

You can tap the small menu and it will open the Maps application to that position so you can get directions to it using Google Maps. Tapping a user in the Who’s Here? section or the mayor will open an overlay showing information about that user (badges, mayorships, etc.) and will give you the option to add them as a friend if you aren’t already. If you look in the Tips & To-do section, you can add a new tip for the venue or a to-do for yourself and the venue by selecting the appropriate button.

Below the map are a series of buttons for meta content. From left to right: Flickr, Banks & ATMs, Parking, and (optionally) Yelp. Tapping yelp will open the venue in the Yelp web site for reviews and other information. Not all venues have Yelp links. Parking will give you a list of parking lots near the venue to help you find a place to park. Banks & ATMs will give you a list of nearby banks and ATMs in case you need some cash. The Flickr button will allow you to view either photos on Flickr tagged with the venue, or Flickr photos nearby. You can tap a photo to view it larger in the Web Browser. You can also tap Upload to upload a new photo to Flickr. Once you fill in all the information for the photo, it’ll be automatically tagged with the venue’s ID using Flickr’s machine tag feature (foursquare:venue=1234) to link the photo to a venue.

When you’re ready to check-in to the venue, tap the big Check-in button across the bottom of the screen in the zBar. After tapping it, you’ll be presented with a dialog box. Generally, you’ll just use the defaults and tap Check-in. However, you can add a shout to your check-in to say something about it (“Excited about this burger!”, “Watching ‘Harry Potter’”), opt whether to show your friends where you are (if not, you’ll still be checked-in and awarded points, badges, etc., but your friends will see you as “Off the Grid”. This is great if you’re checking-in to a surprise party, or maybe you’re at the jewelry store to buy an engagement ring), opt to share on Twitter (if you linked your Twitter account in your settings on the foursquare website), and opt to share the check-in on Facebook (if you linked your Facebook account in your settings on the foursquare website). Keep in mind, if you decide to not share with your friends, the check-in will not go to Facebook, but will still go to Twitter. This is a foursquare bug.

After your check-in goes through, you’ll be presented by a Check-in Result dialog. It’ll verify the venue you checked-in to, tell you any points you were awarded, show you any badges you unlocked, show you any specials at that venue or near it, and it’ll tell you the mayor of the venue (and whether you stole it or still have it).

Venue Map
One the Venues scene, you can tap the magenta button and select Map. This will show you a Google map of your position and icons for all the venues nearest you. Tapping on a marker on the map will give you the name of a venue and a link to the venue’s info.

Friends
When you first tap the Friends button on the zBar, you’ll be given a list of your friends’ most recent check-ins. Tapping on one of your friends will bring you to their profile to see their badges and mayorships and contact info. You can tap the magenta button and select Map and view a Google map of your friends’ locations. You can search for new friends by selecting Search from the magenta button menu. You can search by name only right now. However, tapping Find Friends via Twitter, if you have Twitter linked to your foursquare account, it’ll go through your Twitter followers and find show you users on foursquare you aren’t already friends with. To see the full list of all of your friends in alphabetical order, select List from the magenta button menu. You can also tap Pending Requests to see if anyone has requested to be your friend. Tapping the user here will show you their profile and give you the option of accepting or denying the request.

Tips
This scene will list, first, all of the tips for venues near you, followed by any tips you’ve created or added to your to-do list. Tapping a tip will ask you if you’ve done it or if you want to do it. If you’ve done it, it marks it as done, if you want to do it, it adds it to your to-do list.

Shout
A shout is basically a check-in without a venue. It’s sort of like a status update. Performing a shout will show your status as the shout in all foursquare apps, so instead of seeing your last check-in (“@ Some Bar”), your friends will see your shout. This is useful for things like “Heading downtown, anyone wanna join me for a drink?” and the like. If you share on Twitter, it’ll post the shout as a tweet on twitter. If you share on Facebook, it’ll set your Facebook status to the shout. This is a good way to use foursquare as a slim Twitter/Facebook client.

Profile
Tapping Profile will show you your foursquare profile. It’ll list your mayorships, your badges, and your last 30 check-ins/shouts. Tapping a venue in the mayorship list, or the history list will open that venue’s detail scene, allowing you to check-in or get any other info about the venue.

Board
This is the foursquare Leaderboard. It defaults to the Friends view, which will show the rankings of you vs. all of your friends. Tapping the magenta button will give you a menu to switch between Friends view and City view. City view shows you the top 100 people in the city nearest you. Keep in mind that leaderboards reset every Sunday night at midnight (technically, 12:00:00 Monday morning).

Preferences & Accounts
You can access the Preferences dialog from the application menu. Tapping the top Set Up Account button will allow you to set up your foursquare account information, if you changed your password or something similar. Note that you may need to restart the app for it to take affect.

GPS Accuracy lets you decide how accurate your venue results are. When you first start Foursquare, it’ll get the fastest GPS position it can and show you all the venues near that position. If that initial position is less accurate than your preference setting, the app will continue to get a more accurate position in the background. Once a new position is found, if it is more accurate than the initial position, you’ll get a Refresh button at the top of the venues list. Tapping it will give you a new list of venues. If the new position is less accurate or equal to the initial position, you will not be notified and you can continue using the app with the initial position and venues.

Units lets you select if you want to use SI units (miles, inches, etc.) or metric units (meters). This will be reflected in distances for venues and tips.

Number of Venues to Show let’s you select how many venues to show in the Nearby Venues list. It’s initial value is 15. If you are in a very populated area (say, downtown in a big city, or a shopping mall) you may not find the venue you want because they all will be 0.0 or 0.1mi away from you. Allowing more venues to list will give you greater possibilities of seeing the correct venue since venues are listed closest to furthest. (So, if a venue is 0.1mi away, but the first 15 venues are 0.0mi away, you wouldn’t see that venue unless you increased the number of venues to show.)

Finally, at the bottom, is where you will set up your Flickr account for uploading photos. If you just want to view nearby or venue photos, this is unnecessary, but it is necessary if you wish to upload new photos. Tap the Set Up Flickr Account button to walk through the steps of setting up your account. If you’ve already done this, your account username is displayed in this section.