Ctrip Air Ticket iOS Widget Practice

Author | Derek Yang, senior R&D manager at Ctrip, focuses on iOS development and cross-terminal technology research and is keen on exploring new technologies.

1. Introduction

In September 2020, Apple released iOS 14.0, which has made significant functional improvements compared to previous versions. A very important point is that users can define their own desktop more personally, and Widget is the protagonist of this feature.

Recently, we received a product requirement that requires the implementation of several widgets related to air ticket business. This article summarizes the experience of stepping on the pitfalls and filling the pits during the development and launch of this requirement.

Widget, commonly known as small component, is one of the many App Extensions launched by Apple. Therefore, before introducing Widget, you need to first understand App Extension and its working principle.

2. Introduction to App Extension

Starting from iOS 8.0, the development of App Extension has been supported to meet the needs of enriching Apps.

2.1 What is App Extension?

App Extension is an application extension as the name implies. So it is not an application, but implements a specific and well-defined custom task.

This task is customized by the developer and follows the system-specific extension policy, which is provided to the user when the user interacts with other applications or the system.

After being compiled, App Extension becomes a binary file with the suffix .appex. It cannot be distributed and installed independently and must be attached to the App.

An App can mount multiple types of App Extensions. So far, Apple has launched 33 App Extensions, including Photo Editing, Share, Custom Keyboard, and Widget. See the figure below:

2.2 How App Extension works

The life cycle of an App Extension is different from that of a regular App. It requires an App that contains the Extension (Containing App) and an App that invokes the Extension (Host App).

When the user invokes the Extension through the Host App, the system instantiates the Extension, and the life cycle of the Extension begins, and the Extension begins to perform its own tasks. Later, when the task execution is completed or the user ends the task through the Host App, or the system ends its process for some reason, the life cycle of the Extension ends.

Official profile picture:

The communication relationship between Extension, Containing App and Host App is shown in the following official website diagram:

As can be seen from the figure, App Extension and Host App can communicate directly, but App Extension and Containing App do not communicate directly.

This design ensures that the App Extension is isolated from the containing app during runtime and does not depend on the app. Even when the Extension is running, the containing app will not actively run, and there is no communication between the containing app and the host app.

However, in actual application scenarios, there will still be a need to communicate with the containing app. The solution provided by the system here is to use shared storage between the two to solve the problem of data communication. The App Extension needs to open the containing app and attach some parameters, which can be achieved through the Open Url method.

The official illustration is as follows:

The detailed data sharing method will be introduced in detail in the subsequent Widget section. After a preliminary understanding of App Extension, let's analyze Widget in detail.

3. Introduction to Widget

Widgets are programs that can be added to the user's desktop or run independently in the "Today View".

The predecessor of Widget is Today Extension, which was first launched in iOS 8.0 and abandoned in iOS 14.0. Widget was launched in iOS 14.0. In fact, there are big differences between the two:

In terms of appearance, Today Extension can only be added to the negative one screen, and there are only two sizes: expanded and collapsed. Developers can customize the layout size of this area. Widgets can not only be added to the negative one screen, but also to the desktop, side by side with apps, and support three styles (small: 2x2, medium: 4x2, large: 4x4), which do not support custom sizes.

Widget development uses Apple's newly launched WidgetKit, UI development can only use SwiftUI, and Today Extension uses UIKit. Therefore, for widget development, technical knowledge of Swift and SwiftUI is required.

Xcode12 no longer supports adding Today Extension. For apps with existing Today Extension, the system still displays them in the reserved area of ​​the negative one screen, and they cannot be dragged, moved, or deleted like widgets. Only the original rules are retained.

The display effects of three styles: small, medium and large:

Rounded corners are built-in

The actual rendering sizes of the three sizes on different devices are shown in the following official website data screenshots:

iPhone

iPad

The current demand for air tickets only requires two styles: small card and medium card.

4. Introduction to Widget Development Framework

4.1 Single/multiple widget configuration

The entry points for single and multiple widgets in actual code are different.

A single widget needs to implement the Widget protocol

 @main ​
 struct Widget1 : Widget {
 let kind : String = "widgetTag"
 var body : some WidgetConfiguration {
 ...
 }
 }

Multiple Widgets need to implement the WidgetBundle protocol

 @main ​
 struct TripWidgets : WidgetBundle {
 @WidgetBundleBuilder ​
 var body : some Widget {
 Widget1 ()
 Widget2 ()
 Widget3 ()
 ...
 }
 }

To add a widget, the user needs to go to the system widget addition page, which will display some simple information for the user to view.

The specific configuration of the displayed information is as follows:

 struct Widget1 : Widget {
 let kind : String = "widgetTag"
 var body : some WidgetConfiguration {
 StaticConfiguration ( kind : kind , provider : Provider ()) { entry in
 Widget1View ( entry : entry )
 }
 .configurationDisplayName ( "Travel Inspiration" )
 . description ( "The next journey begins immediately" )
 . supportedFamilies ([ WidgetFamily . systemSmall , WidgetFamily . systemMedium ])
 }
 }

4.2 Widget overall structure

1) Each Widget needs to return a WidgetConfiguration, which can be divided into two types:

• Editable widget IntentConfiguration
• Non-editable StaticConfiguration2) Each WidgetConfiguration requires a Provider and a ViewContent.

Provider is used to refresh the data layer and has three main functions:

• placeholder (used to return the default display data Model)
• getSnapshot (used to render the UI display when calling out to add widgets)
• getTimeline (for data and UI refresh after adding to the user's desktop)

ViewContent is used for UI display and comes in three sizes: 2x2 (Small), 4x2 (Medium), and 4x4 (Large)

API overall architecture serial diagram:

4.3 Widget refresh strategy

Since the widget is added to the user's desktop, the refresh also needs system management. The system defines a refresh rule for this purpose. It is implemented through the provider's getTimeline. The basic principle is to submit a set of data for refreshing the UI in the future to the system. Each data is bound to a time, and then the system renders the preset data to the user according to the time point.

The provider is defined as follows:

 public protocol TimelineProvider {
 associatedtypeEntry : TimelineEntry
 typealias Context = TimelineProviderContext
 func placeholder ( in context : Self . Context ) - > Self . Entry
 func getSnapshot ( in context : Self . Context , completion : @ escaping ( Self . Entry ) - > Void )
 func getTimeline ( in context : Self . Context , completion : @ escaping ( Timeline < Self . Entry > ) - > Void )
 }

The Timeline structure is as follows:

 public struct Timeline < EntryType > where EntryType : TimelineEntry {

 public let entries : [ EntryType ]

 public let policy : TimelineReloadPolicy

 public init ( entries : [ EntryType ], policy : TimelineReloadPolicy )
 }

Parameters for constructing a Timeline

entries: [EntryType] binds data and time. Custom data entities need to comply with the TimelineEntry protocol.

The specific implementations of TimelineEntry all require a date and a data.

TimelineEntry is defined as follows:

 public protocol TimelineEntry {
 var date : Date { get }
 var relevance : TimelineEntryRelevance ? { get }
 }

policy: TimelineReloadPolicy refresh policy

TimelineReloadPolicy is the configuration object responsible for determining the next update strategy.

The system uses the getTimeline method of the Provider to perform a callback for the data refresh operation. In this method, the developer encapsulates the obtained data submission into a TimelineEntry, adds the Timeline refresh policy, and submits it to the system to finally achieve refresh.

Here, the system provides the following three refresh strategies:

1) atEnd, after refreshing all the dates and data given in entries, call getTimeline again to update the refresh strategy.

2) after: used to specify a time in the future. Calling getTimeline will update the refresh policy.

3) never, after adding and executing once, no more policy refresh will be executed.

4.4 App and Widget Association & Interoperability

1) The data association between Widget and App follows the specification of App Extension. The system provides two ways to share data: NSUserDefaults and NSFileManager. The prerequisite is to enable the App Groups function.

The NSUserDefaults way

 //live
 NSUserDefaults * userDefaults = [[ NSUserDefaults alloc ] initWithSuiteName : @ "group.xxx.xxx.xx" ];
 [ userDefaults setObject : @ "test_content" forKey : @ "test" ];
 [ userDefaults synchronize ];
 //Pick
 NSUserDefaults * userDefaults = [[ NSUserDefaults alloc ] initWithSuiteName : @ "group.xxx.xxx.xx" ];
 NSString * content = [ userDefaults objectForKey : @ "test" ];

NSFileManager

 // live
 NSURL * containerURL = [[ NSFileManager defaultManager ] containerURLForSecurityApplicationGroupIdentifier : @ "group.xxx.xxx.xx" ];
 containerURL = [ containerURL URLByAppendingPathComponent : @ "testfile" ];
 [ data writeToURL : containerURL atomically : YES ];

 //Pick
 NSURL * containerURL = [[ NSFileManager defaultManager ] containerURLForSecurityApplicationGroupIdentifier : @ "group.xxx.xxx.xx" ];
 containerURL = [ containerURL URLByAppendingPathComponent : @ "testfile" ];
 NSData * value = [ NSData dataWithContentsOfURL : containerURL ];

2) When the App information changes, the widget is refreshed automatically. The system provides the following methods to achieve this:

 WidgetCenter . shared . reloadTimelines ( ofKind : "widgetTag" )

3) Widget wakes up the App

To redirect using Unviersal Links/URL Schema, the control can be configured in the following two ways:

• widgetURL (the widget only supports clicks on the entire area)
• Link (Small cards do not support it, but medium and large cards can support local area jumps)

When a card is opened, the following lifecycle methods of the App will be called. If you need to jump to a specific page, you can do routing here.

 func scene ( _ scene : UIScene , openURLContexts URLContexts : Set < UIOpenURLContext > ) {
 //URLContexts.first?.url.absoluteString
 ... .
 }

V. Summary of project development experience

Generally speaking, you can quickly implement a widget by following the official development documentation, but there are always some limitations and problems in actual development. The following is a summary of some of the problems and limitations we encountered during project development.

5.1 Limitation of the number of widgets

The official document shows that each App can be configured with up to 5 widgets. You can add multiple WidgetExtension targets to the App, or add multiple widgets to a WidgetExtension target. Each widget supports up to three styles: systemSmall, systemMedium, and systemLarge. A total of up to 15 widgets can be added to the desktop.

Each widget can be added multiple times, depending on the user's operation. (The local simulator environment can be more than 5, but the actual release has not been verified)

5.2 Not all SwiftUI components are available

WidgetKit limits the widget UI to be implemented by SwiftUI, but not all SwiftUI components are available for widgets. If an unsupported component is encountered, WidgetKit will ignore it when rendering.

For specific components that can be used, please refer to the official documentation.

5.3 Image loading issues

Since the mechanism provided by the system requires pre-set data, we initially tried to load the image control in the same way as the App, but found that the image was not loaded. The reason is that it cannot be done asynchronously here, and the Image needs to be obtained synchronously.

In addition, the image here should not be too large, which will also affect the loading. The specific size depends on the processing capacity of the system at that time. (In actual tests, a 200k image could not be loaded)

5.4 Widget click event

Small cards only support widgetURL, and the entire card area can only respond to one event. Medium and large cards can support Link, and can support clicks in multiple areas. Clicking an area that does not have widgetURL and Link set will invoke the containing app by default.

Clicking the Widget and Link method of the Widget can only open the main containing app. Even if the URL maintains the schema of other apps, other apps cannot be opened.

5.5 Notes on code sharing

The official introduction emphasizes that when sharing code, the introduced API must be supported by AppExtension, otherwise it will be rejected during review.

• SharedApplication related API
• With NS_EXTENSION_UNAVAILABLE flag (HealthKit, EventKit UI in iOS 8.0)
• Access camera/microphone (except iMessage)
• Execute long-running background tasks
• Receive data with AirDrop (can send data)

For details, see Using an Embedded Framework to Share Code.

5.6 Limitation of refresh times

Although the system provides these refresh plans, there are certain limitations and discrepancies in the actual number of runs.

• The policy refresh frequency should be at least 5 minutes apart (if it is less than this interval, it may be inaccurate. Although the refresh mechanism provides API support, the actual refresh is still controlled by the system. Not every refresh you add will work accurately).
• In order to reduce the burden on the system, a layer of machine learning is applied on this basis. The actual refresh will be dynamically allocated based on the visible frequency and time of the widgets on the user's phone, the time of the last reload, and the activity status of the main app.

5.7 System Active Refresh Mechanism

At the same time, the refreshes caused by the following system behaviors will not be counted in the refresh count:

• The application corresponding to the widget is in the foreground
• The application corresponding to the widget has an active audio or navigation session
• Change the phone system region
• Dynamic Type or accessibility settings changes

5.8 Size Issue

The widget is eventually compiled into a binary file with the suffix .appex, which is the same as AppExtension. It is inside the ipa file, so the size is shared with the main App.

5.9 Hot fix issues

There is no hot repair plan at the moment, so it is necessary to do a good job of online testing and handling the backup logic.