Instructions

Instructions is a library for adding customizable coach marks (onboarding overlays) to iOS projects for both iPhone and iPad.

Note: The maintainer has marked this project as deprecated. For new projects, it is recommended to migrate to SwiftUI and use Apple's TipKit instead. However, the library will continue to receive bug fixes and compatibility updates for newer Xcode/iOS versions.

Key Features:

• Customizable highlight system, views, and positions.
• Skippable tours and pilotable flows from code.
• Support for App Extensions, Right-to-left (RTL) layouts, and size transitions (orientation/multi-tasking).
• Animatable coach marks and partial UIVisualEffectView support.

In Xcode, navigate to File > Swift Packages > Add Package Dependency and enter the following URL:

https://github.com/ephread/Instructions

To install manually without a dependency manager:

1. Drag the Instructions.xcodeproj into your application's Xcode project navigator.
2. Select your application project in the project navigator.
3. Select your target and go to the General panel.
4. Scroll down to the Embedded Binaries section.
5. Click the + button and select Instructions.framework from the Product directory.

To install using Carthage, add the following line to your Cartfile:

gitub "ephread/Instructions" ~> 2.3.0

Then, run the following commands to update and build the framework:

$ carthage update
$ carthage build

In Instructions 2.0.0, the state properties on CoachMarkController.flow (the FlowManager) have been renamed to include an is prefix.

// 2.0.0 FlowManager Properties
public var isStarted: Bool
public var isPaused: Bool

When migrating to Instructions 2.0.0, update the properties on CoachMarkController.overlay (the OverlayManager) to the following new names:

// 2.0.0 OverlayManager Properties
public var backgroundColor: UIColor
public var isUserInteractionEnabled: Bool 
public var isUserInteractionEnabledInsideCutoutPath: Bool
public var areTouchEventsForwarded: Bool

To begin the tour, call start(in:) on your CoachMarksController. It is recommended to call this in viewDidAppear rather than viewDidLoad to ensure the view hierarchy is ready. To prevent animation artifacts, call stop(immediately: true) in viewWillDisappear.

override func viewDidAppear(_ animated: Bool) {
    super.viewDidAppear(animated)
    self.coachMarksController.start(in: .window(over: self))
}

override func viewWillDisappear(_ animated: Bool) {
    super.viewWillDisappear(animated)
    self.coachMarksController.stop(immediately: true)
}

To install using CocoaPods, add the following to your Podfile:

source 'https://github.com/CocoaPods/Specs.git'
# Instructions is only supported for iOS 13+, but it
# can be used on older versions at your own risk,
# going as far back as iOS 9.
platform :ios, '9.0'
use_frameworks!

pod 'Instructions', '~> 2.3.0'

Then, execute the install command in your terminal:

$ pod install

App Extensions cannot use UIApplication.sharedApplication(). Instructions provides a specific scheme/framework for this purpose.

CocoaPods Setup

In your Podfile, use InstructionsAppExtensions for your extension target:

target 'Instructions App Extensions Example' do
  pod 'Instructions', '~> 2.3.0'
end

target 'Keyboard Extension' do
  pod 'InstructionsAppExtensions', '~> 2.3.0'
end

Frameworks (Carthage / Manual)

Embed both Instructions.framework and InstructionsAppExtensions.framework.

Importing:

• In regular apps: import Instructions
• In App Extensions: import InstructionsAppExtensions

Before installing fastlane, ensure you have the latest version of the Xcode command line tools installed on your system.

xcode-select --install

To allow users to skip the tour:

1. Set skipView to a view conforming to CoachMarkSkipView. This view must implement a skipControl: UIControl? getter.
2. (Optional) Use the CoachMarksControllerDataSource method coachMarksController(_:constraintsForSkipView:inParent:) to return [NSLayoutConstraint] defining the skip button's position.