[SDK-568] Add stable cross-SDK identifiers to IterableDataRegion

[franco-zalamena-iterable]

📝 Summary

Add stable cross-SDK identifiers and lookup factories to IterableDataRegion, and log instead of silently falling back when a region is unrecognised.

🎟️ Jira Ticket: SDK-568

📖 Description

SDK-568 asks for a typed data region across the SDKs. Android already had it — IterableDataRegion has been a Java enum with US/EU since 3.6.0 (MOB-6309), IterableConfig defaults to US, and the builder setter is @NonNull-typed. The divergence the epic describes lives on iOS (config.dataRegion is a raw String, so a typo compiles and misroutes data) and Web (isEuIterableService boolean).

So this PR hardens Android into the shared reference shape rather than redesigning it. Everything is additive — no breaking change, and no action required from clients.

Deprecated

• IterableConstants.BASE_URL_API and BASE_URL_LINKS. Both are hardcoded to the US data region, are unused by the SDK (verified: zero references outside their own declarations), and contradict the configured IterableDataRegion. They still resolve to the same values, so nothing breaks. Named 3.12.0 as the removal version in both the javadoc and the CHANGELOG — assuming this ships in 3.11.0, that's one minor of runway. Deliberately named rather than left as "a future major": the last Android major was 3.0.0 (2018), while public API does get removed in minors (3.5.5 dropped setEncryptionEnforced, 3.8.0 dropped CBC encryption). An unnamed target is exactly how BASE_URL_API survived this long as dead public API. If 3.11.0 isn't the release this lands in, the named version needs adjusting to keep the window intact.

Reviewer notes

Not done deliberately: setDataRegion(String) / setDataRegion(int) builder overloads. Adding them would make an existing setDataRegion(null) call an ambiguous-overload compile error, since IterableDataRegion and String are unrelated reference types — source-breaking. The static from(...) factories give wrappers the same capability with no ambiguity.

getEndpoint() stays public. Narrowing it is the one breaking change available here and it isn't worth it.

Follow-up not in this PR: nothing in the repo will remind anyone to actually remove the constants at 3.12.0. That needs tracking in the 3.12.0 release scope, or it repeats the pattern it's meant to fix.

🧪 How to test?

How to test the changes added?

Unit tests: ./gradlew :iterableapi:testDebugUnitTest

New coverage in IterableDataRegionTest.kt (9 tests) — endpoints match the data centers, identifiers match the other SDKs, from() by region code / iOS-style endpoint URL / numeric code, case- and whitespace-insensitivity, unsupported-value fallback for both overloads, and identifier round-tripping. IterableConfigTest.kt adds nullDataRegionFallsBackToUs (via reflection, since the null is only reachable from Java).

Manual check of the logging path:

IterableConfig config = new IterableConfig.Builder()
    .setDataRegion(IterableDataRegion.from("eu-west-1"))  // unsupported
    .build();

Expect a warning tagged IterableDataRegion naming the supported values (US (0), EU (1)) and a fallback to US. Then confirm IterableDataRegion.from("EU") and from(1) both resolve to EU and that requests go to https://api.eu.iterable.com/api/.

📚 Docs PR if applicable

TODO — the new identifiers/factories and the 3.12.0 deprecation are customer-facing and should be documented before release.

[joaodordio]

These warnings never reach logcat. IterableLogger.w checks Log.WARN >= getLogLevel(), and at the point from() and setDataRegion() run we are still building the config, so getLogLevel() reads the pre-init default IterableConfig whose logLevel is Log.ERROR.

That makes the check 5 >= 6, so the message is dropped.

Note this is not fixable by the integrator either: sharedInstance.config is only swapped for the customer's config in initialize() (IterableApi.java:817), so even .setLogLevel(Log.VERBOSE) in the same builder chain is too late.

I confirmed this with a probe test using Cursor, IterableLogger.w is gated out while IterableLogger.e reaches android.util.Log. Given the failure mode is EU-destined data silently going to the US data center, I would use IterableLogger.e for the unrecognised-region path and add a test asserting the log fires. Otherwise the CHANGELOG line about it no longer resolving silently is not true for anyone.

[franco-zalamena-iterable]

thanks for the catch, this was a good finding and is now fixed.

One exception, from(null) / from("") stays at warning. That's the documented default rather than a misconfiguration, and ERROR there would fire for every wrapper app that never sets a region.

[joaodordio]

We can use the static final string TAG here instead of the "magic string"!