Introduction

This website holds the documentation for TourForge, an open source set of software that makes it easy to create custom tour guide apps. TourForge has two main components: the TourForge tour builder (often just referred to as TourForge) and the software library TourForge Guide.

The TourForge tour builder, located at https://tourforge.github.io/builder/, is a web application that provides a simple interface to build the tour data files that are used by TourForge Guide. A work-in-progress tutorial on how to use TourForge is available in our guide on using the tour builder.

TourForge Guide is a Flutter library providing a baseline with the majority of features needed by a tour guide application. Although almost all of the work has already been done for you, building your app with the TourForge Guide library still requires some software engineering knowledge (or a lot of patience). You will need to set up your development environment and follow the guide on building an app.

Using the tour builder

This guide is currently a WIP as features of tour build webapp continues to change and evolve.

Setting up your development environment

Prerequisite

It is highly recommended to have the following devices to develop and deploy your own OpenTourBuilder instances on both iOS and Android:

  • MacBook
  • iPhone
  • Android

You need the following registered accounts:

  • Apple ID
    • You should only use exactly one unique account for all Apple development devices due to special code signing requirement.
  • Google Account
  • GitHub

Additionally, completing and having these following items handy will speed up the setup process:

  • GitHub fine-grained personal access token with Public repositories (read-only) access.
    • Follow this section of the documentation (https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)
    • If you are a team member of OpenTourBuilder with write access, Your token must be setup this way instead:
      • All repositories access
      • Repository permissions with Contents set to Read and write
      • Resource owner is opentourbuilder

MacBook Setup

Before you do anything else, login on the Mac through System Settings. This section assumes that you have an accessible administrator user account on the MacBook and is currently running at least MacOS 13 Ventura at the time of writing.

Software Installation

You can install these in-order:

  • Install Homebrew

    • Follow this documentation (https://brew.sh/)

  • Install Ruby

    • Follow this documentation (https://www.ruby-lang.org/en/documentation/installation/#homebrew)

  • Install CocoaPods

    • Follow this documentation (https://guides.cocoapods.org/using/getting-started.html)

  • Install Xcode

    • Follow this article (https://matteomanferdini.com/install-xcode/#xcode-app-store)

  • Install Flutter SDK

    • Follow this documentation (https://docs.flutter.dev/get-started/install/macos)

  • Install Visual Studio Code

    • Follow this documentation (https://code.visualstudio.com/docs/setup/mac)

  • Install Android Studio

    • Follow this documentation (https://developer.android.com/studio/install#mac)

  • Install Android SDK Command-Line Tools

    • Open this GUI at (https://developer.android.com/studio/intro/update#sdk-manager)
    • Switch to SDK Tools tab, you can find the required item in the list

Clone Git Repository

NOTE: Why did this instruction exists? Isn't SSH key enough?

Open the terminal at a desired location and run these commands, line-by-line:

git init
git remote add origin https://<YOUR_FINEGRAINED_TOKEN_HERE>@github.com/<ORGANIZATION_OR_USERNAME>/<REPOSITORY>.git
git checkout main && git fetch

The repository is ready to use. Repeat this entire process for any additional repository that you want to clone. Note that you must read README.md for the repository for any additional setups.

iPhone Setup

Complete the following steps:

  • Login using a preferred Apple ID
  • Enable developer mode
    • Follow this documentation (https://developer.apple.com/documentation/xcode/enabling-developer-mode-on-a-device)

Android Setup

Complete the following steps:

  • Login using a preferred Google account
  • Enable developer options and then enable USB debugging
    • Follow the top portion of this documentation (https://developer.android.com/studio/debug/dev-options)

Building an app

Since TourForge Baseline is a Flutter library, it can be used to create a tour guide application with customized branding without code changes to the library itself. Keep in mind that branding is only one piece of the puzzle: tours themselves must be created as well.

The steps below should help give you an idea of what is required to create a tour guide app with TourForge Baseline.

  1. Create a fork of the TourForge Baseline repository and clone it to your local machine.
  2. Get the app running by following the instructions in the TourForge Baseline repository's README.
  3. Upload your tour content, created using TourForge, to a webserver. The content with its full directory structure should be accessible via HTTPS. You will need to know the base URL of where the content is accessible, for example: https://example.org/tour-content/.
  4. Change the URL in the app/lib/main.dart to whatever your content's base URL is.
  5. Check and see if the app now loads your content instead of the default content. If not, here are some troubleshooting tips:
    • Is it still showing the default content? If so, you might not have changed the right URL.
    • Is the content not loading at all?
      • Check the logs to investigate the exact error.
      • Most likely, content not loading means that the URL is wrong or your webserver is not properly configured to serve the files.
      • Try manually requesting the tour data from your webserver to see if it works that way.
  6. Customize the application's branding as you see fit.

Publishing an app

Prerequisite

You need the following registered accounts, the same one used in development machine setup:

  • Apple ID
  • Google Account

Depending on which platform you want to publish, you will need to have an active Google Play Developer and/or an active Apple Developer Program membership. You can also be a member of an organization with active memberships and publish under their behalf. If that is the case, make sure you have the necessary permission to create and publish a new application, usually Administrator role will be enough.

Apple App Store Publication

If you have not experienced publishing a mobile app before, this process can be daunting.

Register New Identifier

Follow this article (https://developer.apple.com/help/account/manage-identifiers/register-an-app-id/).

  • Enable push notification capabilities
  • Make sure to find and replace all instances of the old application ID with the newly created ID <-- NOTE: needs clarification on exactly what this means and why do we do it

Create New App Record

Follow this article (https://developer.apple.com/help/app-store-connect/create-an-app-record/add-a-new-app). The Apple developer portal has a lot of help panels/bubbles, it is highly recommended to read through them.

  • The Bundle ID is the one used to create the identifier in the previous section
  • Platform should only be iOS

To archive and upload the app to Apple, follow the relevant section at (https://github.com/tourforge/baseline/blob/main/README.md).

Google Play Store Publication

If you have not experienced publishing a mobile app before, this process can be daunting. This article can help you understand the general process of publishing to Google Play Store (https://medium.com/@the_manifest/how-to-publish-an-app-on-google-play-a-step-by-step-guide-80f9f533e370). Note that you do not have to do anything regarding monetization since the app is free. Additionally, Google has an entire knowledge base to guide you through step-by-step (https://support.google.com/googleplay/android-developer/answer/9859152?hl=en). You can proceed to the next article in the series via the right-side navbar.

The high-level overview of the process is as follows:

  1. After you've created your Google Play developer account, you can create apps and set them up using Play Console.
  2. After you create your app, you can start setting it up.
    • Your app’s dashboard will guide you through all the most important steps to get your app available on Google Play.
    • You’ll start by providing details about your app’s content, and entering information for your Google Play store listing.
  3. After that, you can move onto app release; this guides you through pre-release management, and testing.
  4. The final step is launching your app on Google Play.

During the publication process, you should follow these recommended options:

  • New app should be App as opposed to Game
  • App should be Free
  • App category should be Travel & Local

To build a signed release bundle, follow the relevant section at (https://github.com/tourforge/baseline/blob/main/README.md).

Issues & Workarounds

Apple App Listing Screenshots Requirements

Apple has an ever-changing screenshot requirements for all apps. Usually this is of little issue since we can simulate whatever devices to take screenshots. The problem is that the debug banner shows up because Xcode REQUIRES Debug mode in simulator, which causes the debug banner to show up in the screenshot.

Once you have researched what specific iOS device you need to simulate to make the screenshots. You must do 2 things:

  • Switch Mapbox.framework to the x86_64 simulator version if you haven't already done so (more details in the TourForge/baseline README).
  • Check out this thread (https://stackoverflow.com/questions/48893935/how-can-i-remove-the-debug-banner-in-flutter) and add the necessary bool value in the MaterialApp constructor.

Now you can run the app in the simulator without debug banner and happy screenshotting.