Testing with custom OneBusAway and OpenTripPlanner servers

We support testing custom OneBusAway and OpenTripPlanner servers in OneBusAway Android. You can use this feature to try out a new test server that you've set up, but aren't ready to publicize in the Regions API yet.

Before doing anything, check out the system architecture diagrams to understand how OBA Android communicates with other servers. and what features they provide.

Also, note that while you can test your OBA server with a HTTP URL (see section below), you'll need to enable SSL for HTTPS before launching in the Regions API.

Two mechanisms

There are two independent ways to point the app at a server you control:

1. The API-URL preferences documented below (Settings → Advanced). These set an OBA and/or OTP URL directly and switch the app out of region resolution entirely — there is no region, just a pair of URLs. Good for poking at a test server.
2. A custom region — an onebusaway://add-region?name=…&oba-url=… deep link, which creates a real named region that persists, appears in the region picker, and survives regions-directory refreshes. See DEEP_LINKING.md. Better for a deployment you'll come back to, and the only one of the two that can carry a sidecar/analytics config.

They mostly don't stack: applying any region (including a custom one) always clears the custom OBA URL preference, so whichever you did last decides where transit data comes from.

The custom OTP URL is narrower — RegionRepository.applyRegion clears it only when the region being applied actually publishes an otpBaseUrl. So if you set a custom OTP URL and then switch to a region with no trip planner of its own (including a custom region added without otp-url), that custom OTP URL stays in effect. That is long-standing behaviour for every region, not something custom regions introduce; clear the preference by hand if you don't want it.

Configuration

In the app, go to "Settings->Advanced". You should see a screen like:

You can use the following directions to add a custom OneBusAway API server and/or a custom OpenTripPlanner server. After entering the server name and path, hit the back button twice to exit the Settings screen, and the app will re-initialize with the new URL(s).

Testing without SSL

We strongly encourage you to configure your server to use SSL for secure communication via HTTPS - this is required for launching as a new region in the Regions API due to requirements in Android and iOS.

If you want to test a server without SSL enabled, you'll need to build your own version of this app with an edited onebusaway-android/src/main/res/xml/network_security_config.xml file to add an exception for your server. This is an Android restriction for plain text HTTP communication - see https://developer.android.com/training/articles/security-config for details.

OneBusAway API Server

You can enter a server URL in a few different formats, including:

• example.onebusaway.org
• example.onebusaway.org/onebusaway-api-webapp (if you deployed to the default path)
• https://example.onebusaway.org
• https://example.onebusaway.org/onebusaway-api-webapp

OpenTripPlanner API Server

You can enter a server URL in a few different formats, including:

• example.opentripplanner.org/otp
• http://example.opentripplanner.org/otp

Note that if your server is using SSL/HTTPS, you currently need to enter the entire URL:

• https://example.opentripplanner.org/otp

For older OpenTripPlanner servers (circa pre-v0.19.0) that don't include "/otp/routers/default" in the path, you can include the path up until the "plan" endpoint.

For example, if your server "plan" endpoint is at http://example.opentripplanner.org/tripplanner/plan?..., then you can enter the following as the custom OTP URL:

• example.opentripplanner.org/tripplanner/