+ * The parameter is annotated {@link NonNull}, but Java callers are not held to that at + * compile time: passing {@code null} falls back to {@link IterableDataRegion#US} and logs an + * error rather than throwing. + *
+ * To resolve a region from a string or numeric identifier (for example when bridging from a + * cross-platform wrapper), use {@link IterableDataRegion#from(String)} or + * {@link IterableDataRegion#from(int)}, which fall back to + * {@link IterableDataRegion#US} and log on unrecognised values. + * + * @param dataRegion enum value that determines which endpoint to use, defaults to + * IterableDataRegion.US; {@code null} is treated as + * {@link IterableDataRegion#US} */ @NonNull public Builder setDataRegion(@NonNull IterableDataRegion dataRegion) { + if (dataRegion == null) { + IterableLogger.e(TAG, "setDataRegion received null, defaulting to " + IterableDataRegion.US.getRegionCode()); + this.dataRegion = IterableDataRegion.US; + return this; + } this.dataRegion = dataRegion; return this; } diff --git a/iterableapi/src/main/java/com/iterable/iterableapi/IterableConstants.java b/iterableapi/src/main/java/com/iterable/iterableapi/IterableConstants.java index 6c896f6d7..403c12a05 100644 --- a/iterableapi/src/main/java/com/iterable/iterableapi/IterableConstants.java +++ b/iterableapi/src/main/java/com/iterable/iterableapi/IterableConstants.java @@ -11,7 +11,18 @@ public final class IterableConstants { public static final String ACTION_PUSH_REGISTRATION = "com.iterable.push.ACTION_PUSH_REGISTRATION"; //Hosts + /** + * @deprecated These constants are hardcoded to the US data region and are unused by the SDK. + * Use {@link IterableDataRegion#getEndpoint()} instead, which respects the configured region. + * Scheduled for removal in 3.12.0. + */ + @Deprecated public static final String BASE_URL_API = "https://api.iterable.com/api/"; + /** + * @deprecated Unused by the SDK and hardcoded to the US data region. + * Scheduled for removal in 3.12.0. + */ + @Deprecated public static final String BASE_URL_LINKS = "https://links.iterable.com/"; //API Fields diff --git a/iterableapi/src/main/java/com/iterable/iterableapi/IterableDataRegion.java b/iterableapi/src/main/java/com/iterable/iterableapi/IterableDataRegion.java index aec57c0f2..8175741a3 100644 --- a/iterableapi/src/main/java/com/iterable/iterableapi/IterableDataRegion.java +++ b/iterableapi/src/main/java/com/iterable/iterableapi/IterableDataRegion.java @@ -1,16 +1,114 @@ package com.iterable.iterableapi; +import androidx.annotation.NonNull; +import androidx.annotation.Nullable; + +/** + * Data region determining which data center and endpoints the SDK sends data to. + * Defaults to {@link #US}; EU-hosted projects must select {@link #EU}. + */ public enum IterableDataRegion { - US("https://api.iterable.com/api/"), - EU("https://api.eu.iterable.com/api/"); + US(0, "US", "https://api.iterable.com/api/"), + EU(1, "EU", "https://api.eu.iterable.com/api/"); + + private static final String TAG = "IterableDataRegion"; + private final int code; + private final String regionCode; private final String endpoint; - IterableDataRegion(String endpoint) { + IterableDataRegion(int code, String regionCode, String endpoint) { + this.code = code; + this.regionCode = regionCode; this.endpoint = endpoint; } public String getEndpoint() { return this.endpoint; } + + /** + * Stable numeric identifier for this region, matching the values used by the React Native and + * Flutter SDKs. Unlike {@link #ordinal()} this is guaranteed not to shift if regions are added. + */ + public int getCode() { + return this.code; + } + + /** + * Stable short identifier for this region (for example {@code "EU"}), matching the values used + * by Iterable's other SDKs. It currently matches {@link #name()}, but is stored separately for + * the same reason {@link #getCode()} does not use {@link #ordinal()}: renaming an enum constant + * must not change an identifier that wrappers and persisted configuration already rely on. + */ + @NonNull + public String getRegionCode() { + return this.regionCode; + } + + /** + * Resolves a region from its short identifier (e.g. {@code "EU"}), accepting either case. Also + * accepts a full API endpoint URL, so values from the iOS SDK's string-based data region can be + * passed through unchanged. + *
+ * Unrecognised values fall back to {@link #US} and are logged as an error, matching the + * behaviour of Iterable's other SDKs. A null or blank value also falls back to {@link #US}, + * which is the documented default rather than a misconfiguration. + * + * @param value region identifier, or {@code null} + * @return the matching region, or {@link #US} if the value is not recognised + */ + @NonNull + public static IterableDataRegion from(@Nullable String value) { + if (value == null || value.trim().isEmpty()) { + IterableLogger.w(TAG, "No data region specified, defaulting to " + US.regionCode); + return US; + } + + String normalized = value.trim(); + for (IterableDataRegion region : values()) { + if (normalized.equalsIgnoreCase(region.regionCode) || normalized.equalsIgnoreCase(region.endpoint)) { + return region; + } + } + + // Error level, not warning: this runs while the config is still being built, and + // IterableLogger reads the pre-init config (ERROR) until initialize() swaps it in. + IterableLogger.e(TAG, "Unsupported data region \"" + value + "\", defaulting to " + US.regionCode + + ". Supported values: " + supportedRegionCodes()); + return US; + } + + /** + * Resolves a region from its numeric identifier, as used by the React Native and Flutter SDKs. + *
+ * Unrecognised values fall back to {@link #US} and are logged as an error, matching the
+ * behaviour of Iterable's other SDKs.
+ *
+ * @param code region identifier, see {@link #getCode()}
+ * @return the matching region, or {@link #US} if the code is not recognised
+ */
+ @NonNull
+ public static IterableDataRegion from(int code) {
+ for (IterableDataRegion region : values()) {
+ if (region.code == code) {
+ return region;
+ }
+ }
+
+ IterableLogger.e(TAG, "Unsupported data region code " + code + ", defaulting to " + US.regionCode
+ + ". Supported values: " + supportedRegionCodes());
+ return US;
+ }
+
+ private static String supportedRegionCodes() {
+ StringBuilder builder = new StringBuilder();
+ for (IterableDataRegion region : values()) {
+ if (builder.length() > 0) {
+ builder.append(", ");
+ }
+ builder.append(region.regionCode).append(" (").append(region.code).append(")");
+ }
+ return builder.toString();
+ }
}
diff --git a/iterableapi/src/main/java/com/iterable/iterableapi/IterableRequestTask.java b/iterableapi/src/main/java/com/iterable/iterableapi/IterableRequestTask.java
index 8c66c885d..fb728bfdb 100644
--- a/iterableapi/src/main/java/com/iterable/iterableapi/IterableRequestTask.java
+++ b/iterableapi/src/main/java/com/iterable/iterableapi/IterableRequestTask.java
@@ -87,9 +87,6 @@ static IterableApiResponse executeApiRequest(IterableApiRequest iterableApiReque
String baseUrl = getBaseUrl();
try {
- if (overrideUrl != null && !overrideUrl.isEmpty()) {
- baseUrl = overrideUrl;
- }
if (iterableApiRequest.requestType == IterableApiRequest.GET) {
Uri.Builder builder = Uri.parse(baseUrl + iterableApiRequest.resourcePath).buildUpon();
diff --git a/iterableapi/src/test/java/com/iterable/iterableapi/IterableConfigTest.kt b/iterableapi/src/test/java/com/iterable/iterableapi/IterableConfigTest.kt
index 646105f1f..84d2ecf57 100644
--- a/iterableapi/src/test/java/com/iterable/iterableapi/IterableConfigTest.kt
+++ b/iterableapi/src/test/java/com/iterable/iterableapi/IterableConfigTest.kt
@@ -1,12 +1,23 @@
package com.iterable.iterableapi
+import android.util.Log
+import com.iterable.iterableapi.unit.TestRunner
import org.hamcrest.Matchers.`is`
import org.hamcrest.Matchers.nullValue
import org.junit.Assert.*
+import org.junit.Before
import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.shadows.ShadowLog
+@RunWith(TestRunner::class)
class IterableConfigTest {
+ @Before
+ fun clearLogs() {
+ ShadowLog.clear()
+ }
+
@Test
fun defaultDataRegion() {
val configBuilder: IterableConfig.Builder = IterableConfig.Builder()
@@ -21,6 +32,24 @@ class IterableConfigTest {
val config: IterableConfig = configBuilder.build()
assertThat(config.dataRegion, `is`(IterableDataRegion.EU))
}
+
+ /** Only reachable from Java, where the `@NonNull` parameter can still be passed null. */
+ @Test
+ fun nullDataRegionFallsBackToUs() {
+ val builder = IterableConfig.Builder()
+ val setter = IterableConfig.Builder::class.java
+ .getMethod("setDataRegion", IterableDataRegion::class.java)
+ setter.invoke(builder, null)
+ assertThat(builder.build().dataRegion, `is`(IterableDataRegion.US))
+
+ // Builder methods run before initialize() swaps in this config, so IterableLogger is still
+ // reading the pre-init ERROR level: anything below ERROR never reaches logcat.
+ val errors = ShadowLog.getLogsForTag("IterableConfig")
+ .filter { it.type == Log.ERROR }
+ .map { it.msg }
+ assertEquals(errors.toString(), 1, errors.size)
+ assertTrue(errors.single(), errors.single().contains("setDataRegion received null"))
+ }
@Test
fun defaultWebViewBaseUrl() {
diff --git a/iterableapi/src/test/java/com/iterable/iterableapi/IterableDataRegionTest.kt b/iterableapi/src/test/java/com/iterable/iterableapi/IterableDataRegionTest.kt
new file mode 100644
index 000000000..255b75dfb
--- /dev/null
+++ b/iterableapi/src/test/java/com/iterable/iterableapi/IterableDataRegionTest.kt
@@ -0,0 +1,130 @@
+package com.iterable.iterableapi
+
+import android.util.Log
+import com.iterable.iterableapi.unit.TestRunner
+import org.hamcrest.Matchers.`is`
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertThat
+import org.junit.Assert.assertTrue
+import org.junit.Before
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.shadows.ShadowLog
+
+@RunWith(TestRunner::class)
+class IterableDataRegionTest {
+
+ @Before
+ fun clearLogs() {
+ ShadowLog.clear()
+ }
+
+ @Test
+ fun endpointsMatchDataCenters() {
+ assertEquals("https://api.iterable.com/api/", IterableDataRegion.US.endpoint)
+ assertEquals("https://api.eu.iterable.com/api/", IterableDataRegion.EU.endpoint)
+ }
+
+ /** These identifiers are part of the cross-SDK contract; changing them breaks the wrappers. */
+ @Test
+ fun stableIdentifiersMatchOtherSdks() {
+ assertEquals(0, IterableDataRegion.US.code)
+ assertEquals(1, IterableDataRegion.EU.code)
+ assertEquals("US", IterableDataRegion.US.regionCode)
+ assertEquals("EU", IterableDataRegion.EU.regionCode)
+ }
+
+ @Test
+ fun fromRegionCode() {
+ assertThat(IterableDataRegion.from("US"), `is`(IterableDataRegion.US))
+ assertThat(IterableDataRegion.from("EU"), `is`(IterableDataRegion.EU))
+ }
+
+ @Test
+ fun fromRegionCodeIsCaseAndWhitespaceInsensitive() {
+ assertThat(IterableDataRegion.from("eu"), `is`(IterableDataRegion.EU))
+ assertThat(IterableDataRegion.from("Eu"), `is`(IterableDataRegion.EU))
+ assertThat(IterableDataRegion.from(" EU "), `is`(IterableDataRegion.EU))
+ }
+
+ /** iOS expresses the data region as the endpoint URL itself, so those values must resolve. */
+ @Test
+ fun fromIosStyleEndpointUrl() {
+ assertThat(
+ IterableDataRegion.from("https://api.eu.iterable.com/api/"),
+ `is`(IterableDataRegion.EU)
+ )
+ assertThat(
+ IterableDataRegion.from("https://api.iterable.com/api/"),
+ `is`(IterableDataRegion.US)
+ )
+ }
+
+ @Test
+ fun fromUnsupportedStringFallsBackToUs() {
+ assertThat(IterableDataRegion.from("APAC"), `is`(IterableDataRegion.US))
+ assertThat(IterableDataRegion.from(""), `is`(IterableDataRegion.US))
+ assertThat(IterableDataRegion.from(" "), `is`(IterableDataRegion.US))
+ assertThat(IterableDataRegion.from(null as String?), `is`(IterableDataRegion.US))
+ }
+
+ @Test
+ fun fromCode() {
+ assertThat(IterableDataRegion.from(0), `is`(IterableDataRegion.US))
+ assertThat(IterableDataRegion.from(1), `is`(IterableDataRegion.EU))
+ }
+
+ @Test
+ fun fromUnsupportedCodeFallsBackToUs() {
+ assertThat(IterableDataRegion.from(2), `is`(IterableDataRegion.US))
+ assertThat(IterableDataRegion.from(-1), `is`(IterableDataRegion.US))
+ assertThat(IterableDataRegion.from(Int.MAX_VALUE), `is`(IterableDataRegion.US))
+ }
+
+ /** Round-trips guard the wrappers, which serialize the region and resolve it back. */
+ @Test
+ fun identifiersRoundTrip() {
+ for (region in IterableDataRegion.values()) {
+ assertThat(IterableDataRegion.from(region.code), `is`(region))
+ assertThat(IterableDataRegion.from(region.regionCode), `is`(region))
+ assertThat(IterableDataRegion.from(region.endpoint), `is`(region))
+ }
+ }
+
+ /**
+ * These factories run while the config is still being built, so IterableLogger is still reading
+ * the pre-init config's ERROR level. Anything below ERROR is dropped before it reaches logcat,
+ * which would leave a misconfigured region silently sending data to the US data center.
+ */
+ @Test
+ fun unsupportedStringIsLoggedAtDefaultLogLevel() {
+ IterableDataRegion.from("APAC")
+
+ val message = errorLogs().single()
+ assertTrue("log should name the rejected value: $message", message.contains("APAC"))
+ assertTrue("log should list supported values: $message", message.contains("US (0), EU (1)"))
+ }
+
+ @Test
+ fun unsupportedCodeIsLoggedAtDefaultLogLevel() {
+ IterableDataRegion.from(7)
+
+ val message = errorLogs().single()
+ assertTrue("log should name the rejected code: $message", message.contains("7"))
+ assertTrue("log should list supported values: $message", message.contains("US (0), EU (1)"))
+ }
+
+ @Test
+ fun recognisedValuesAreNotLoggedAsErrors() {
+ IterableDataRegion.from("EU")
+ IterableDataRegion.from("https://api.eu.iterable.com/api/")
+ IterableDataRegion.from(0)
+
+ assertTrue(errorLogs().toString(), errorLogs().isEmpty())
+ }
+
+ private fun errorLogs(): List