Sandbox and Production

Develop against your free Sandbox with approved test phones, then ship with your Production key and address.

Every Bubbl company has two workspaces. Each has its own SDK API key and its own API address, and the key and the address must match.

Pass the address as shown: don't add /api/v1 (the SDK adds it), and it must be https://. If the key and the address don't match, the server answers wrong_environment and the SDK stops, logging that the key and the address don't match and which address to start with instead.

Bubbl also warns in the log when the key doesn't suit the build: a Sandbox key (pk_test_) in a release build, which only serves approved test phones, or a Production key (pk_live_) in a debug build, which gets your live campaigns.

First run in the Sandbox#

1. Start Bubbl with your pk_test_… key and the Sandbox address.
2. Run the app on a phone. It registers and waits as pending: no geofences, pushes or messages yet.
3. Find the code Bubbl logs at start, in Logcat (tag BubblSDK) or the Xcode console: Bubbl sandbox: approve this device with code K7Q-2MX. It's logged as a warning, so it shows at the default log level.
4. In the dashboard, open Configuration › Test Devices and approve the phone.

Approving test devices#

Configuration › Test Devices is only in a Sandbox (the dashboard side is in Test devices). Owners, admins and developers can approve and revoke phones; everyone else in the team can view the page. There are three ways to approve a phone:

• The Pending list. Match the code your app logged against the Code column and choose Approve.
• Add a test device. Opens a panel that watches for new phones for 10 minutes. Open your app with the Sandbox key, and approve your phone as it appears.
• A registration code, from your app. For QA teams and device farms. Under Registration codes, choose Issue code; the code is shown once and approves one phone within 24 hours. Your app passes it to registerTestDevice, for example from a hidden debug menu, and the phone is approved at once.

// From a coroutine; there's also a Callback<TestDeviceResult> overload
val result = Bubbl.registerTestDevice(code)
if (!result.approved) showError(result.message)

let result = await Bubbl.registerTestDevice(code)
if !result.approved { showError(result.message) }

final result = await Bubbl.registerTestDevice(code);
if (!result.approved) showError(result.message);

const { approved, message } = await Bubbl.registerTestDevice(code);
if (!approved) showError(message);

registerTestDevice never throws. When the phone isn't approved, message says why, in words you can show whoever typed the code: a wrong, used or expired code, the Sandbox's test devices all taken, no connection, or Bubbl not started yet.

Bubbl.diagnostics() tells you where a phone stands: environment is "sandbox" or "production" once the server has said, and testDevice (Sandbox only) has the status, "pending" or "approved", and the code while it's pending.

Limits#

• A Sandbox has up to 25 approved test devices. Approved phones unused for 30 days go back to pending, with a new code.
• Pending phones that nobody approves drop off after 7 days.
• If a Sandbox has as many pending phones as it allows, Bubbl logs that it's full and tries again in a few hours. Approve or remove some in the dashboard.
• A revoked phone has to register again before it can be approved.

What's different in the Sandbox#

• Notifications from a Sandbox have a headline starting "Sandbox · ", and Bubbl's notification screen shows a SANDBOX ribbon. If you draw notifications yourself, check isSandbox on the message and mark them too.
• Test devices and their events stay out of Production's reports.
• A Sandbox can send pushes with its own Firebase and Apple credentials or with Production's: see Dashboard setup.

Going live#

In a Sandbox, Configuration › Developers has a Going live checklist:

1. Subscribe to a paid plan. Production opens on any paid plan.
2. Add push credentials to Production. Firebase for Android and Apple Push for iOS, in the Production workspace (or keep sending with Production's from the Sandbox, as above).
3. Ship the pk_live_ key and the Production address. Swap both in your release build. Nothing else in your code changes.

To bring over what you built, use Copy to Production in the Sandbox's amber bar: owners and admins pick the campaigns, notifications, location groups and locations to copy. Campaigns arrive paused. See Copy to Production.

Before you release, also check:

• Android: the Location permissions declaration in the Play Console. The SDK declares background location, so every app using Bubbl fills it in. See Location and geofences.
• iOS: ad hoc, TestFlight and App Store builds register their push tokens as production, so Apple Push needs your app's key in the workspace the build uses. See Push notifications.
• Consent: if your users must agree first, start with requireConsent. See Consent and user data.

An install belongs to the key it was started with. Start it with another key (the Production key after the Sandbox one, or a rotated key) and it starts afresh as a new device: what Bubbl kept on the phone, its queued events included, is cleared first, and the user's consent is kept.