Android App: How to version your integrations

Version the contract, not the phone

“How to version your integrations” on an Android SMS gateway is usually a request to stop copy-pasting curl into five microservices. The phone is a modem. The thing that bit-rots is the contract between your backends and the control plane: auth header, JSON body, webhook events, and what you do on timeout.

Live request fields belong in Developer Center. This guide is the ops shape: one adapter, explicit versions, canaries, and no silent dual-send. Pricing is still devices plus SMS volume. You bring the Android and operator credit. Free is 300 SMS lifetime.

Language samples on /codebase-php and /codebase-csharp are REST examples. Pin a git tag of your wrapper, not a fantasy SDK version.

1. v0

   Scattered curls

2. v1

   One adapter

3. v2

   Signed webhooks

4. v3

   Idempotent OTP

What actually changes between versions

Bump a version when the caller must change behavior: a new required field, a changed error code, a webhook envelope, or a new auth scheme. Do not bump because you renamed an internal function. Do not bump because you updated the APK.

“If OTP and billing alerts share an unversioned helper, the next ‘small payload tweak’ will ship as an outage with a commit message that says refactor.”

Keep the adapter boring: timeout, retry with jitter, idempotency key, mapping from gateway ids to your verification rows. Everything else — template pick, locale, fraud rules — stays above the adapter so v2 of send does not rewrite compliance.

Pairing and QR flow: setup. A new integration version should not require re-pairing every phone. If it does, you coupled the wrong layers.

Compatibility matrix

Webhook event versions

Webhooks are how delivery and inbound replies reach you. Verify the signature header. Persist event ids. If you introduce a new event shape, either add a field that old parsers ignore or stand up a second endpoint until every consumer moves.

Dual-running v1 and v2 handlers that both resend OTP on message.failed is how you double-text a user. One owner for retries. Version the payload, not the policy — or version both, explicitly.

Inbound replies on the same SIM are a feature of two-way SMS. If v2 of your bot starts auto-replying STOP with a new phrase, that is a product change, not a JSON tweak. Review it like a release.

Keys, pairing, and staff

Rotate API keys on staff change. A versioned adapter should read the key from env, never from a notebook. If v1 and v2 must coexist, prefer one key with server-side routing over two keys that junior on-call mixes up.

Document which plan environment you hit. Free (300 SMS lifetime) is for proving the path, not for a second “prod.” Developer is 25,000 SMS per year. Paid device caps stay 2 / 5 / 15 on Starter / Professional / Business.

External practice worth stealing: semantic versioning of your library, as described in semver.org. Apply it to the adapter package, not to GSM.

Rollout without a silent outage

• Ship v2 adapter behind a flag defaulting to v1 for OTP.
• Send 1% of non-customer canaries through v2 for a day.
• Compare accept vs fail rates and webhook completeness, not “felt faster.”
• Only then flip customer login. Keep v1 compiled for a rollback measured in minutes.
• After APK updates, re-test the critical path on a spare device. Updating without breaking pairing is an app-ops topic; do not hide it inside an API changelog.

Isolate OTP from bulk. A versioned campaign importer that retries a whole CSV is allowed to be loud. A versioned OTP adapter is not. OTP use case vs bulk CSV should not share a retry class.

Where the adapter should live

Put the gateway client in one package: sendSms, mapStatus, verifyWebhook. OTP, billing alerts, and bulk each import it. They do not open raw HTTPS. When Developer Center changes a field, you change one module and tag it.

Contract tests against a recorded fixture beat hitting production from CI. Save a golden request/response pair per adapter version. If the live API adds an optional field, v1 tests still pass. If a required field appears, v1 fails loudly in CI instead of in Friday OTP.

Feature flags belong around the adapter choice, not inside JSON builders scattered across services. One flag:smsAdapter = v1 | v2. OTP reads it. Bulk may lag a week. That lag is allowed; dual retry owners are not.

What counts as breaking

• Renaming a JSON key the adapter sends.
• Changing error mapping so a radio busy looks like a client 400.
• Altering webhook signature verification so old endpoints 403.
• Defaulting retries from 0 to 3 on OTP.
• Switching device routing so OTP lands on the marketing SIM.

Non-breaking: extra response fields you ignore, a faster queue, an APK that still pairs. Those are changelog notes, not semver majors. Staff still re-test pairing after APK updates because OEM behavior is not a spec.

Environment split: do not point staging adapters at the only production phone. A second device on Free (300 SMS lifetime) is enough to prove v2. Exhausting Free pauses sends on that plan until you upgrade — do not discover that mid-canary.

Changelog hygiene

Write the adapter changelog for on-call, not for marketing. Include: version, date, flag name, rollback command, and which product flows flipped. Link Developer Center for field names. Link this article for why you version at all.

If you publish internal OpenAPI for the adapter, keep it generated from code. Drift between a wiki table and the client is how v1 and v2 both ship in the same binary under different function names.

Next steps

Make one module the only thing that talks to the gateway. Tag it v1. Put webhooks behind a signature check. Then you have something to version. Plans: pricing.