Skip to main content

Progressive Rollout (Canary), Geo-Targeting, and Strategies

The /rollout page (src/app/rollout/page.tsx), together with the CountrySelectorModal and UpdateStrategyModal components accessible from release views, gives operators fine-grained control over who receives an OTA patch, where, and under which network/UX constraints.

1. Progressive Canary Rollout (rolloutPercentage)​

Rather than exposing 100% of the mobile fleet to a new patch at once, authorized operators (ROLE_ADMIN or ROLE_SRE_ADMIN, holding the EDIT_ROLLOUT permission) can dynamically adjust the rollout percentage via PATCH /api/admin/v1/patches/{id}/rollout:

  • Quick Preset Steps in the UI:
    • 0% (Pause / Freeze): No new devices download the patch (without rolling back devices that already installed it).
    • 10% (Initial Canary): Limited exposure to monitor live telemetry and the Circuit-Breaker.
    • 25% (Quarter Fleet): Progressive expansion.
    • 50% (Half Fleet): Large-scale validation.
    • 100% (Full Rollout): All eligible devices receive the patch.

Deterministic Hashing Algorithm (deterministic algorithm)​

In TkushPatch Server(clientId, patchNumber, rolloutPercentage), device eligibility is computed in a 100% deterministic, stateless manner:

String seed = (clientId != null ? clientId : "anonymous") + ":" + patchNumber;
deterministic algorithm deterministic algorithm = new deterministic algorithm;
deterministic algorithm.update(seed.getBytes(StandardCharsets.UTF_8));
long bucket = deterministic algorithm.getValue() % 100; // Bucket between 0 and 99
return bucket < rolloutPercentage;

Key Guarantee: A device hashed into bucket 7 (included at the 10% step) will always remain included when the operator increases the rollout slider to 25%, 50%, and 100%. Including patchNumber in the seed also ensures that the exact same 10% of users are not perpetually selected as guinea pigs across consecutive patches.

2. Country Targeting (CountrySelectorModal)​

When a single mobile application serves multiple national subsidiaries (sharing the same app_id), CountrySelectorModal (src/components/deployments/CountrySelectorModal.tsx) restricts a patch to specific countries (allowedCountries) via PATCH /api/admin/v1/patches/{id}/countries:

  • Two Distribution Modes:
    • Global Distribution (ALL): allowedCountries is empty ([]), making all countries eligible.
    • Country Targeting (CUSTOM): Only devices reporting an ISO-3166-1 alpha-2 country_code present in allowedCountries receive the patch offer during POST /api/v1/patches/check.
  • Built-in Catalog of 34 Countries (Grouped by Region):
    • Africa (21 countries): Cameroon (CM), Côte d'Ivoire (CI), Senegal (SN), Gabon (GA), Republic of the Congo (CG), DR Congo (CD), Chad (TD), Central African Republic (CF), Equatorial Guinea (GQ), Benin (BJ), Burkina Faso (BF), Mali (ML), Niger (NE), Togo (TG), Guinea (GN), Nigeria (NG), Ghana (GH), Kenya (KE), South Africa (ZA), Morocco (MA), Tunisia (TN).
    • Europe (6 countries): France (FR), Belgium (BE), Switzerland (CH), United Kingdom (GB), Germany (DE), Spain (ES).
    • Americas (3 countries): United States (US), Canada (CA), Brazil (BR).
    • Middle East & Asia (4 countries): United Arab Emirates (AE), China (CN), India (IN), Singapore (SG).
  • Batch Selection: Each region provides a Select All / Deselect All button alongside an instant search bar filtering by country name or 2-letter ISO code.

3. Update Strategies (UpdateStrategyModal)​

The UpdateStrategyModal component (src/components/deployments/UpdateStrategyModal.tsx) configures how the mobile SDK handles the patch via PATCH /api/admin/v1/patches/{id}/strategy (requiring the CONFIGURE_STRATEGY permission):

Update Strategy ModePayload ParametersDevice Behavior
1. Standard (STANDARD)forceCriticalUpdate: false, requireWifi: falseSilent background download over Wi-Fi or cellular data (3G/4G/5G). The patch is seamlessly applied on the next application restart.
2. Data Saver (WIFI_ONLY)forceCriticalUpdate: false, requireWifi: trueRecommended for larger patches (> 2 MB): background download is deferred until the device connects to a Wi-Fi network, preserving the user's cellular data plan.
3. Forced Critical (FORCED_CRITICAL)forceCriticalUpdate: true, requireWifi: false (or true)Security emergency or blocking hotfix: the patch descriptor returns force_critical_update: true, instructing the host app to display a blocking modal requiring immediate installation before continuing.