OBAKit

OBAKit is a total rewrite of OneBusAway for iOS in the Swift programming language.

Purpose and Goals

This codebase is built as a set of reusable Swift packages, which can be used to make new apps or augment existing apps on iOS and watchOS.
This codebase is meant to provide an easy way for transit agencies to create their own custom-branded transit apps without needing to fork the OneBusAway source code.
This codebase is intended to be easy to understand, test, and maintain. We try to emphasize clarity over cleverness, even at the risk of being somewhat more verbose at times.

Quick Start

You can generate the project without opening Xcode first:

# Install Xcode from the App Store, then (once):
#   sudo xcode-select -s /Applications/Xcode.app
#   open Xcode once to finish first-launch setup

brew install xcodegen          # required to generate OBAKit.xcodeproj
./scripts/setup                # checks deps, runs generate_project for OneBusAway
# or: ./scripts/setup KiedyBus
# add --no-watch to scripts/generate_project for iOS-only builds without the watchOS platform
open OBAKit.xcodeproj

scripts/setup verifies xcodebuild + XcodeGen, reminds you about signing, and calls scripts/generate_project. The generated OBAKit.xcodeproj is gitignored — always regenerate after pulling. Xcode resolves the project's Swift Package Manager dependencies when you open it.

Signing / bundle IDs for contributors outside the OBA org

Shared Apps/OneBusAway/project.yml points at the Open Transit Software Foundation team. For a personal build:

cp Apps/OneBusAway/local.yml.example Apps/OneBusAway/local.yml
Put your 10-character Team ID in DEVELOPMENT_TEAM
Re-run ./scripts/setup

Apps/*/local.yml is gitignored and is copied into the generated project, so it overrides the shared development team. PRODUCT_BUNDLE_IDENTIFIER is not a self-contained local override: app groups, associated domains, Apple Pay, URL schemes, and user-activity identifiers are still branded for the official apps. Change those identifiers together in a white-label configuration before using a different bundle ID on a device. More detail: wiki/Get-Started.

White Labeling

The iOS codebase is a white-label product, read more about white-labeling at wiki/White-Label.

Custom Regions

You can quickly add a custom region to the app by creating a specially formed link and then tapping on it in Mobile Safari:

Example:

onebusaway://add-region?name=Unitrans&oba-url=https%3A%2F%2Fonebusaway-unitrans.onrender.com%2F

Breaking it down:

Scheme: onebusaway
Host: add-region
Query Params:
- name - the name of the region
- oba-url - the URL encoded address of the server

Internationalization and Localization

Note: There's a lot more to be written on this topic. Don't hesitate to ask questions if something is wrong or confusing.

Translations live directly in this repository as Apple .strings files (OBAKit/Strings/*.lproj and OBAKitCore/Strings/*.lproj), with Apps/OneBusAway/*.lproj/InfoPlist.strings for system permission prompts. To improve a translation or add a language, edit those files (UTF-8) and open a pull request.

Run scripts/extract_strings to regenerate the English source files from code after adding new OBALoc/Strings entries. New languages must also be added to CFBundleLocalizations in Apps/Shared/app_shared.yml.

Using OBAKit as a Swift Package

This repository is a Swift package with three library products:

Product	Platforms	What it is
`OBAKitCore`	iOS 18, watchOS 11	Models, networking, regions, and persistence. Application extension safe.
`OBAKit`	iOS 18	The app's view controllers and UI.
`OBAKitWatch`	watchOS 11	The watch app's screens and host.

Add it to your app in Xcode (File → Add Package Dependencies…) or in a Package.swift:

.package(url: "https://github.com/OneBusAway/onebusaway-ios.git", .upToNextMinor(from: "26.4.0"))

Versions are the app's release tags; 26.4.0 is the first that ships a Package.swift. The API is not stable. It is shaped by the OneBusAway apps, and any release, minor ones included, can change it. Pin to a minor version, as above, and read the release notes before you move.

If you use OBAKit's Siri and Shortcuts actions, Xcode merges their metadata into your app automatically. Your app must declare its own AppShortcutsProvider (pass it to AppConfig.appShortcutsProvider) and ship the AppIntents.strings and AppShortcuts.strings tables; see Apps/Shared/CommonClient and docs/shortcut-live-activity.md. Don't add an AppIntentsPackage that includes OBAKit: the system would ignore every intent in your app.

The code is Swift only; there is no Objective-C interface.

Documentation

This project uses Apple's DocC to generate its API documentation, so no extra tooling is required beyond Xcode. To build the documentation, run:

scripts/docs

This produces a statically-hostable site in the api-docs/ directory. On every push to main, the Documentation GitHub Actions workflow regenerates the docs and deploys them to GitHub Pages.

How-To's

Protobuf

To make modifications to the local copy of gtfs-realtime.proto, you will need to install some new tools via the brew command:

brew install protobuf
brew install swift-protobuf

Now, replace the file OBAKitCore/Models/Protobuf/gtfs-realtime.proto with the updated version, and run scripts/proto-gen.sh from the project root.

You can find the latest version of the GTFS-RT protobuf file in the https://github.com/google/transit/ repository.

Generate App Store screenshots

Run scripts/app_store_screenshots from the project root. It captures each slide in the simulator, adds the device frame and caption, and writes finished PNGs to build/app-store-screenshots/slides/. Add --duo for the iPhone Duo set, --watch for the Apple Watch set, or --all-sets for all three. See docs/app-store/README.md for the one-time setup, options, and how to change the slides.

Update macOS/Xcode versions for GitHub Actions CI

Find the latest version of macOS and Xcode here: https://github.com/actions/runner-images/tree/main/images/macos
Update the .github/obakittests.yml file accordingly.
There's no step 3.

Fix "Missing package product" build errors

In Xcode: File Menu -> Packages -> Reset Package Caches

Update Your App's Package.resolved file

Run the script scripts/update_package_resolved

Figure out why SPM dependencies aren't loading correctly

Run this command from the terminal:

xcodebuild -resolvePackageDependencies

Third Party Libraries

These are third party libraries directly included inside of this project.

AwesomeSpotlight

Includes AwesomeSpotlight by Aleksandr Shoshiashvili.

```
Copyright (c) 2017 aleksandrshoshiashvili aleksandr.shoshiashvili@gmail.com

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
```

Polyline

Includes Polyline.swift by Raphaël Mor.

```
The MIT License (MIT)

Copyright (c) 2015 Raphaël Mor

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
```

ProgressHUD

Includes ProgressHUD by Related Code.

```
v13.4

MIT License

Copyright (c) 2020 Related Code.

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
```

SVPulsingAnnotationView

```
Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby
granted, provided that the above copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING
ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL,
DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
```

Visual Effects Shadow

Includes Visual Effects Shadow by Brian Coyner.

```
https://github.com/briancoyner/Visual-Effects-Shadow

MIT License

Copyright (c) 2017 Brian Coyner

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
```

Apache 2.0 License

All other code is made available under the Apache 2.0 license.

Copyright 2018-Present Open Transit Software Foundation

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Name		Name	Last commit message	Last commit date
.claude		.claude
.github/workflows		.github/workflows
.swiftpm/xcode/package.xcworkspace		.swiftpm/xcode/package.xcworkspace
Apps		Apps
OBAKit		OBAKit
OBAKitCore		OBAKitCore
OBAKitTests		OBAKitTests
OBAKitUITests		OBAKitUITests
OBAKitWatch		OBAKitWatch
OBAWidget		OBAWidget
WatchApp		WatchApp
WebResources		WebResources
docs		docs
fastlane		fastlane
scripts		scripts
.gitattributes		.gitattributes
.gitignore		.gitignore
.ruby-gemset		.ruby-gemset
.ruby-version		.ruby-version
.spi.yml		.spi.yml
.swiftlint.yml		.swiftlint.yml
CLAUDE.md		CLAUDE.md
Gemfile		Gemfile
Gemfile.lock		Gemfile.lock
LICENSE		LICENSE
Package.swift		Package.swift
README.markdown		README.markdown

Key	Example	More-tab row
`TutorialURL`	`https://example.com/help`	Tutorials
`PhoneURL`	`tel:+12065551212`	Call Agency
`TextURL`	`sms:+12065551212`	Text Agency
`CustomLinks`	`[{Title, URL}, …]`	Resources (any extra links)

Navigation Menu

Repository navigation

About

Repository files navigation

OBAKit

Purpose and Goals

Quick Start

Signing / bundle IDs for contributors outside the OBA org

White Labeling

More tab contact links

Custom Regions

Internationalization and Localization

Using OBAKit as a Swift Package

Documentation

How-To's

Protobuf

Generate App Store screenshots

Update macOS/Xcode versions for GitHub Actions CI

Fix "Missing package product" build errors

Update Your App's Package.resolved file

Figure out why SPM dependencies aren't loading correctly

Third Party Libraries

AwesomeSpotlight

Polyline

ProgressHUD

SVPulsingAnnotationView

Visual Effects Shadow

Apache 2.0 License

About

Releases

Packages

Used by

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

OBAKit

Purpose and Goals

Quick Start

Signing / bundle IDs for contributors outside the OBA org

White Labeling

More tab contact links

Custom Regions

Internationalization and Localization

Using OBAKit as a Swift Package

Documentation

How-To's

Protobuf

Generate App Store screenshots

Update macOS/Xcode versions for GitHub Actions CI

Fix "Missing package product" build errors

Update Your App's Package.resolved file

Figure out why SPM dependencies aren't loading correctly

Third Party Libraries

AwesomeSpotlight

Polyline

ProgressHUD

SVPulsingAnnotationView

Visual Effects Shadow

Apache 2.0 License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages