Available for the following Plan types:
Fullstory Enterprise*
Fullstory Advanced*
Fullstory Business*
Fullstory Free
*with the following add-on:
Fullstory for Mobile Apps
Available to the following User roles:
Admin
Architect
Standard
Using native data capture on iOS requires adding the Fullstory capture framework to your app. You can add the Fullstory framework to your app in several ways. Choose the approach that best integrates with your existing app build and follow the setup instructions linked below.
As you're implementing the instructions below, you may find it useful to reference a sample app with Fullstory integrated. We have an example of the SDK being implemented into an iOS app here.
Setup
1. Adding the Fullstory framework
Add the Plugin
- From the Xcode menu, select File > Add Packages
- In the dialog, using the Search Bar on the top-right, enter:
https://github.com/fullstorydev/fullstory-swift-package-ios - The fullstory-swift-package-ios should show up. Set the Dependency Rule to Up to Next Major Version and enter the plugin version as 1.54.0, then Add Package
- In the next dialog, make sure the FullStory entry is checked and that your desired Project is listed under Add to Target, then Add Package
Add the Build Phase
- In the project navigator, select your app's Project, then select your app's Target, select Build Phases tab
- From the Xcode menu, select Editor > Add Build Phase > Add Run Script Build Phase
- Double click on the new Run Script phase and rename it to Run FullStory Asset Uploader, and replace the body as below:
"${BUILD_DIR%Build/*}/SourcePackages/artifacts/fullstory-swift-package-ios/fullstory/tools/FullStoryCommandLine" "${CONFIGURATION_BUILD_DIR}/${WRAPPER_NAME}"
Add the Plugin
- In your
Podfile
, under your app's Target, paste the line below:pod 'FullStory', :http =>
'https://ios-releases.fullstory.com/fullstory-1.54.0-xcframework.tar.gz' - Run
pod install
Add the Build Phase
- In the project navigator, select your app's Project, then select your app's Target, select Build Phases tab
- From the Xcode menu, select Editor > Add Build Phase > Add Run Script Build Phase
- Double click on the new Run Script phase to rename it to Run FullStory Asset Uploader, and replace the body as below:
"${PODS_ROOT}/FullStory/tools/FullStoryCommandLine" "${CONFIGURATION_BUILD_DIR}/${WRAPPER_NAME}"
- To update Fullstory in the future, update the URL above and run
pod update FullStory
Add the Plugin
- Download https://ios-releases.fullstory.com/fullstory-1.54.0-xcframework.tar.gz and extract in your app's repository
- In the project navigator, select your app's Project, then select your app's Target, select General tab
- Under Frameworks, Libraries and Embedded Content, click the + button > Add Other... > Add Files... and select FullStory.xcframework in the directory where you extracted it and click Open
- In the Embed column, make sure that Embed & Sign is selected for FullStory.xcframework
Add the Build Phase
- In the project navigator, select your app's Project, then select your app's Target, select Build Phases tab
- From the Xcode menu, select Editor > Add Build Phase > Add Run Script Build Phase
- Double click on the new Run Script phase to rename it to Run FullStory Asset Uploader, and replace the body as below:
path/to/FullStory/tools/FullStoryCommandLine "${CONFIGURATION_BUILD_DIR}/${WRAPPER_NAME}"
2. Add the Plugin Properties
To complete the Fullstory integration, you need to tell the framework which Fullstory organization to capture data to.
- Open your app's
Info.plist
- From the menu, choose Editor > Add Item. Set the key name to
FullStory
, and the type to "Dictionary". - Right click on the
FullStory
row, and choose "Add Row". Set the key name toOrgId
, and the type to "String". For the value, paste in your assigned organization ID.
When configured correctly, the Info.plist
entry should look as follows:
Possible Info.plist
configurations:
Property | Options | Description |
---|---|---|
OrgId |
Required |
Your Org ID |
LogLevel (optional) |
Default: Options: |
Capture FS.log() messages at or above the specified level |
RecordOnStart (optional) |
Default: Options: |
Prevent Fullstory from starting data capture on App Startup |
IncludeAssets (optional) |
Default: Options: varies |
Specify webview file types to upload for playback. This is strongly recommended if you intend to capture WebViews |
ServerUrl (optional) |
Default: Options: varies |
Specify the server url to route Fullstory traffic through |
PreviewMode (optional) |
Default: Options: |
Capture sessions in preview mode |
Setting Org ID
Add your Org ID, which can be obtained by logging into Fullstory. Navigate to Settings > Data Capture and Privacy > Fullstory Setup, where you should see a line that looks like the following:window['_fs_org'] = 'XXXXX';
. This string is your Org ID. For additional help finding your Org ID, check out this article.
Additionally, when you login to your Fullstory account, your Org ID can be found in the URL of your browser.
https://app.fullstory.com/ui/<ORG_ID>/home
Capture FS.log()
Messages
By default, Fullstory will capture any Log statements sent via FS.log()
API above and at 'debug'
level in your application. To change this behavior, update your logLevel
flag.
logLevel 'error'
Any message sent below the specified level will not be sent to Fullstory. For example, if 'info'
level is specified, 'debug'
and 'log'
messages will not be sent. Available options:
assert
error
warning
info
debug
Prevent Fullstory from starting data capture on App Startup
By default, Fullstory will start data capture on app startup. If you want to only start data capture once certain conditions are met, you can set RecordOnStart
flag to false
, which will prevent data capture until FS.restart()
API is explicitly invoked.
RecordOnStart false
Configuring a Relay Server
Requires version 1.37.0
+
By default, Fullstory routes traffic through "https://fullstory.com." To instead route Fullstory traffic through a Relay server, you may add a ServerUrl
key, of type String, with a value of your server's url.
Using Fullstory's Advanced Features
Identifying users and passing custom data to Fullstory
The FS.identify and FS.setUserVars enables you to enrich your Fullstory data with additional variables for use in searches, segments, and integrations. This functionality allows you to pass user information to Fullstory directly from your mobile app. The parameters are:
Objective-C
-
[FS identify:userVars:]
takes aNSString
and an optionalNSDictionary<NSString *, id>
-
[FS setUserVars:]
takes aNSDictionary<NSString *, id>
Swift
-
FS.identify(_:userVars:)
takes aString
and an optional[String : Any]
-
FS.setUserVars(_:)
takes a[String : Any]
Fullstory Initialization Callback
You can implement FSDelegate
to get notified of session data when Fullstory is fully initialized and ready to be used.
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)
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 data capture on or off
Mobile data capture can be toggled on or off from Settings > Data Capture and Privacy > Mobile Data Capture. 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 capture 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. If your application doesn’t use WebViews or you don’t care to capture within WebViews, you can safely ignore this section.
These settings can be configured from Settings > Data Capture and Privacy > Mobile Data Capture.
Note: Fullstory SDK can capture contents ofWKWebView
(iOS) /WebView
(Android) but notSFSafariViewController
(iOS) /Chrome Custom Tabs
(Android). Fullstory for Web may be used to capture contents ofSFSafariViewController
/Chrome Custom Tabs
, but they will be displayed as separate sessions
Asset Uploading for WebViews
By default, the Fullstory build-time tool for iOS (FullStoryCommandLine
) uploads image assets that are part of the Assets.car
files. Additionally, it searches inside the .app
bundle for image assets of file types .jpg
, .jpeg
and .png
within the /assets
directory, and also resources of file type .css
within the /www
directory. For a refresher on the standard iOS app bundle directory hierarchy, consult Apple’s documentation.
Applications that use web technologies heavily (or that include image files outside of an Assets.car
) may need to upload other assets in order for playback to work correctly. To configure the tool to look for additional file types and/or in different directories, you will add an entry in the FullStory
dictionary of your Info.plist
named IncludeAssets
.
- Right click on the
FullStory
row withinInfo.plist
, and choose "Add Row". Set the key name toIncludeAssets
, and the type to "Dictionary". - Right click on the
IncludeAssets
row, and choose "Add Row". Set the key name to the directory name, and the type to "Array". You only need to add a root directory, as the Fullstory build-time tool will recursively search any child directories. - Right click on the directory row and choose "Add Row". Set the value to the extension of the file type you want to include. You may add multiple file types. Repeat this process for each additional directory.
Below is an example that includes css
files in any directories under <bundleroot>/my_directory
, and any css
, ttf
, and jpeg
files under <bundleroot>/my_other_directory
:
Additional topics
Fullstory for SwiftUI Apps
For customers who are already familiar with using Fullstory on iOS with UIKit or React Native apps, Fullstory’s SwiftUI support is a bit different. To learn more, read our article What's Different in Fullstory for SwiftUI? Or the how-to companion article, Integrating Fullstory into a SwiftUI App.
Integrate Fullstory Logs with your App Logging Framework
Data Capture Logs can help you troubleshoot app issues, as well as uncover unintended behavior. In this guide, we're going to review a few popular logging frameworks and how you can integrate them with Fullstory.
Impact on App Size
For apps downloaded from the App Store, after app thinning Fullstory's framework will add ~2MB to your app size.
For apps downloaded from the App Store prior to Apple using app thinning by default (pre-iOS 11), 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.)
To learn more about how app thinning impacts app size, please refer to Apple documentation here: Reducing your app’s size.
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 ~9MB uncompressed to your app, but that’s because app thinning / slicing doesn’t happen for developer builds.
Troubleshooting Missing Assets
Requires version 1.47.0
+
If an app was built without running FullStoryCommandLine
, sessions will be missing some Assets (Images, Stylesheets, etc.) during playback. To remedy this, use the included FullStoryCommandLine
to backfill the missing Assets as below:
- Unzip/Extract your
YourApp.app
file from theYourApp.ipa
archive - Navigate to the directory where you have the
FullStoryCommandLine
and make sure thatFullStoryCommandLine.simulator
also exists - Run
./FullStoryCommandLine YourApp.app --backfill
- Verify that playback now includes the previously missing Assets. Also confirm that calls to
map.json
are no longer resulting in403
on your Browser Network Inspector
Fullstory API
For information on usage, visit our developer docs.