Implementation of Offline Mode Switching in an iOS Retail Client

The article discusses the importance of an offline mode for the Youzan retail client, which must remain functional when network or server failures occur. Offline mode ensures core features such as login, payment, order management, member points, and certain marketing activities continue to work even without server connectivity.

Two main challenges are identified: (1) how to accurately trigger and exit offline mode, and (2) how to handle data processing and synchronization in offline scenarios. The article focuses on the first challenge, using the iOS retail client as a case study.

Technical Implementation of Offline Switching

The client must detect situations that require switching to offline mode, such as unstable Wi‑Fi during peak checkout periods or complete network loss. Two switching mechanisms are provided: manual activation by the user and automatic activation when network or server faults are detected.

An offline module is placed between the business layer and the network layer. Business modules obtain offline‑state changes via dependency injection, while the network layer reports errors to the offline module, which then decides whether to enter offline mode.

Offline State Management

Offline state is determined by three factors: a manual offline flag, network fault detection, and service fault detection. A finite‑state machine ensures the client stays offline as long as any of these factors remain true. The manual flag is persisted in a local file so crashes do not lose the offline state.

Network Fault Detection

The implementation uses Apple’s Reachability library, which relies on SCNetworkReachability . Two usage modes are described:

Synchronous mode obtains the current status via the method:

currentReachabilityStatus

- (NetworkStatus)currentReachabilityStatus {
NSAssert(_reachabilityRef != NULL, @"currentNetworkStatus called with NULL SCNetworkReachabilityRef");
NetworkStatus returnValue = NotReachable;
SCNetworkReachabilityFlags flags;
// 同步模式获取网络连接状态
if (SCNetworkReachabilityGetFlags(_reachabilityRef, &flags)) {
returnValue = [self networkStatusForFlags:flags];
}
return returnValue;
}

Asynchronous mode starts a run‑loop listener:

startNotifier

- (BOOL)startNotifier {
BOOL returnValue = NO;
SCNetworkReachabilityContext context = {0, (__bridge void *)(self), NULL, NULL, NULL};
// 设置回调函数
if (SCNetworkReachabilitySetCallback(_reachabilityRef, ReachabilityCallback, &context)) {
if (SCNetworkReachabilityScheduleWithRunLoop(_reachabilityRef, CFRunLoopGetCurrent(), kCFRunLoopDefaultMode)) {
returnValue = YES;
}
}
return returnValue;
}

The callback notifies the app of status changes:

static void ReachabilityCallback(SCNetworkReachabilityRef target, SCNetworkReachabilityFlags flags, void *info) {
NSCAssert(info != NULL, @"info was NULL in ReachabilityCallback");
Reachability *noteObject = (__bridge Reachability *)info;
[[NSNotificationCenter defaultCenter] postNotificationName:kReachabilityChangedNotification object:noteObject];
}

Because Reachability only reports network reachability, the team adopted the third‑party RealReachability library, which adds ping‑based detection for true server reachability. To avoid frequent toggling between online and offline states, a debounce interval T1 is introduced: the client waits T1 seconds after a detected disconnection before actually entering offline mode.

Service Fault Detection

The offline module also monitors service‑level failures through a four‑stage process:

Network layer error propagation to the offline module.

Local parsing of error information against a whitelist of core business APIs.

Querying a QoS decision system to determine if a backend service is faulty.

Polling the QoS system until the fault is resolved, then updating the offline state.

Diagrams (omitted here) illustrate the data flow for both network and service fault detection.

Outlook

The article concludes by noting that the next challenge is data handling and synchronization for various business modules (account, product, marketing, member, payment, order) during offline operation. Future posts will detail how the client ensures complete checkout functionality without network connectivity.