Getting Started with iOS Recording

A note on FullStory for Mobile Apps

Access to FullStory for Mobile Apps is dependent on your FullStory plan. Please contact your Account Executive or mobile-support@fullstory.com to learn more.

About FullStory for Mobile Apps

FullStory for Mobile Apps includes and requires Private by Default technology that empowers product teams to debug experiences on native mobile applications while proactively respecting end-user privacy. Session replay for mobile apps isn't a screen recording and FullStory never captures screenshots from an end-user's device. Similar to FullStory for the web, where session replay represents a re-creation of a digital experience based on recorded changes in the DOM, FullStory's session replay for mobile apps is based on drawing operations, where text, images, and personal data are masked at the source by default, such that masked data never reaches FullStory's servers. 

Interested in using FullStory to understand and debug mobile app experiences? Request a demo or contact us to learn how to add FullStory for Mobile Apps to your current account plan.

 

Getting Started

Using native recording on iOS requires adding the FullStory capture framework to your app. If you use CocoaPods, you can do this by simply adding the FullStory pod to your application, or you can also add the FullStory dylib to your Xcode project directly. These instructions describe how to implement these two approaches.

 

CocoaPods Installation: adding the FullStory pod

For iOS applications that already use CocoaPods, FullStory distributes a pod specification that you can integrate directly into your existing Podfile

Follow these steps:

  • In your Podfile, in the section for your app's target, paste this line:

pod 'FullStory', :http =>
'https://ios-releases.fullstory.com/fullstory-1.6.2.tar.gz'

  • Run “pod install
  • Add a build phase for FullStory's asset uploader
    • In the project navigator, select your app's project
    • In the editor panel, select your app's target
    • Choose the Build Phases tab
    • Chose Editer > Add Build Phase > Add Run Script Build Phase
    • On the new “Run Script” phase, double-click on the “Run Script” label and rename to “Run FullStory Asset Uploader”
    • If it’s not already, re-order the build phase so it’s the last step
    • Click the disclosure triangle next to the build phase to expand it
    • Replace the body of the script with (it should all be on one line):
      "${PODS_ROOT}/FullStory/tools/FullStoryCommandLine" "${CONFIGURATION_BUILD_DIR}/${WRAPPER_NAME}"
  • To upgrade FullStory in the future, update the FullStory release URL in your Podfile and run “pod update FullStory

 

Manual Installation: adding the FullStory framework

For iOS applications that do not use CocoaPods, you can directly integrate the FullStory framework with your app.

Follow these steps:

  • Download & Extract FullStory
  • Add FullStory.xcframework in your app’s embedded frameworks
    • In the project navigator, select your app’s project
    • In the editor panel, select your app’s target
    • Choose the General tab
    • Under Frameworks, Libraries, and Embedded Content, click the + button
    • Under Add Other, choose Add Files…
    • Navigate to where you extracted FullStory and select FullStory.xcframework.  Click Open
    • In the Embed column, you should see “Embed & Sign” selected for FullStory.xcframework
  • Add a build phase for FullStory’s asset uploader
    • In the project navigator, select your app’s project
    • In the editor panel, select your app’s target
    • Choose the Build Phases tab
    • Choose Editor > Add Build Phase > Add Run Script Build Phase
    • On the new “Run Script” phase, double-click on the “Run Script” label and rename to “Run FullStory Asset Uploader”
    • If it’s not already, re-order the build phase so it’s the last step
    • Click the disclosure triangle next to the build phase to expand it
    • Replace the body of the script with the following line, replacing “path/to/FullStory” with the appropriate path:
      path/to/FullStory/tools/FullStoryCommandLine \
      "${CONFIGURATION_BUILD_DIR}/${WRAPPER_NAME}"


Configure FullStory

To complete the FullStory integration, you need to tell the framework which FullStory organization to record to.

  • Open your app's Info.plist
  • From the menu, Choose Editor > Add Item
  • Set the key name to FSOrgId, type to string, and for the value paste in your assigned ID

Upgrading to FullStory 1.6.0 from an earlier release

If you use CocoaPods to manage dependencies, you can safely skip this section. It's handled automatically.

Starting with our 1.6.0 release, FullStory is distributed in the new XCFramework distribution format supported by Xcode 11. 

XCFramework is an improvement for both framework authors and app developers. On the framework side, it’s easier to produce one distributable that supports both iOS devices and simulators. On the app side, adding a third-party framework involves fewer steps.

Follow these steps to upgrade:

  • Remove existing references to FullStory.framework
    • In the project navigator, in the Filter field at the bottom, enter “FullStory.framework
    • Select any matches and press Delete
    • When asked if you want to remove the reference or move to trash, choose Remove Reference.
  • Add FullStory back as an XCFramework
    • In the project navigator, select your app’s project
    • In the editor panel, select your app’s target
    • Choose the General tab
    • Under Frameworks, Libraries, and Embedded Content, click the + button
    • Under Add Other, choose Add Files…
    • Navigate to where you extracted FullStory and select FullStory.xcframework.  Click Open
    • In the Embed column, you should see “Embed & Sign” selected for FullStory.xcframework


Identifying users and passing custom data to FullStory

On the Web, FullStory offers the FS.identify and FS.setUserVars JavaScript functions to enable you to enrich your FullStory data with additional variables for use in searches, segments, and integrations. This functionality is replicated on iOS to allow you to pass user information to FullStory directly from your native app. The methods behave identically to their JavaScript counterparts linked above. The parameters are simply the Objective-C/Swift equivalents of the original JavaScript parameters:

Objective-C

  • [FS-identify:userVars:] takes a NSString and an optional NSDictionary<NString *, id>
  • [FS setUserVars:] takes a NSDictionary<NSString *, id>

Swift

  • FS.identify(_:userVars:) takes a String and an optional [String : Any]
  • FS.setUserVars(_:) takes a [String : Any]

Preventing FullStory from automatically recording on startup

Added in version: 1.5.1
By default, FullStory will automatically request a session and start recording on app startup. If you need to only start recording the app once certain conditions are met, then you can use the new RecordOnStart feature. Configuring FullStory to not RecordOnStart will prevent recording until you explicitly invoke FS.restart.

To prevent FullStory from recording on start, in your app’s Info.plist, add an FSRecordOnStart key, of type Boolean, with a value of NO.

FullStory Delegate

You can implement the FullStory Delegate protocol FSDelegate to be notified about the session lifecycle.

Objective-C

// File: Appdelegate.m

// Set the FS delegate in `didFinishLaunchingWithOptions`
FS.delegate = self;

// Implement the optional methods
- (void)fullstoryDidTerminateWithError:(NSError *)error {}
- (void)fullstoryDidStartSession:(NSString *)sessionUrl {}
- (void)fullstoryDidStopSession {}

 

Identify

Identify is used to associate your own application-specific id with the active user.

Objective-C

NSString *userId = @"13ff474bae77"; // replace with your user’s Id
NSDictionary *info = @{
@"email": @"user@example.com",
@"displayName": @"Shopping User"
};

[FS identify:userId userVars:info];


Swift

In order for FullStory to be imported and used in Swift you’ll need to make sure that you’ve configured an Objective-C bridging header and @import FullStory; in the bridging header. See Apple’s Importing Objective-C into Swift documentation for help with adding the header.

let userId = "13ff474bae77" // replace with your user’s Id
let info = ["email": "user1@example.com",
"displayName": "Shopping User"
]
FS.identify(userId, userVars: info)

 

Additional topics

FullStory for Mobile Apps Privacy rules

For more information about configuring privacy rules and masking, please consult our FullStory for Mobile Apps Privacy Rules guide. 

Turning mobile recording on or off

Mobile recording can be toggled on or off from Settings > Mobile Recording. This applies across your entire FullStory account.

Configuring domain allowlisting for WebViews

If your application makes use of WebViews, you must explicitly allowlist any domain you wish to record within a WebView. For security and privacy reasons, you should only allowlist domains which are under your control. Wildcards and subdomains are supported using the same scheme as Web domain settings. The key difference between the Web and Mobile settings is that while domain allowlisting is optional on Web, it is mandatory on Mobile if you wish to record content within WebViews. If your application doesn’t use WebViews or you don’t care to record within WebViews, you can safely ignore this section.

These settings can be configured from Settings > Mobile Recording.

Impact on App Size

For apps downloaded from the App Store, FullStory’s framework adds ~ 9MB to your uncompressed app size on device but only ~ 2.8MB to your compressed download size. (Note that compression rates can vary by app.)

Since iOS 9.0 when App Thinning was introduced, the App Store will automatically slice your app into different variants for all devices targeted. In each variant, executables and resources for unsupported architectures or screen sizes are automatically removed.

If your app targets both 32-bit and 64-bit devices (true for iOS 10 or earlier), your App Store submission will include both armv7 and arm64 versions of FullStory.framework (~ 18MB, uncompressed). However, when your users download your app, they’ll only receive the version of FullStory.framework that matches their device (~ 9MB, uncompressed).

Note that FullStory.framework will occupy more space in developer builds. We ship a universal framework that includes a variant for each architecture we support. Currently, that’s arm64, armv7, and x86_64. The full universal framework adds ~ 29MB uncompressed to your app, but that’s because app thinning / slicing doesn’t happen for developer builds.

To learn more about how app thinning impacts app size, see Getting an App Size Report in Technical Q&A QA1795.

 

Need to get in touch with us?

The FullStory Team awaits your every question.

Contact us