LookbackParticipate

Superclass:
NSObject
Declared In:

Introduction

By setting up Participate for your app, you prepare your app for receiving "Participate URLs", and allows it to be used in UX research. Participate is a UI layer on top of of the `LookbackRecorder`, so that Lookback can take care of the full research flow for you.

The Participate flow is completely self contained, so once implemented, you do not need to use the `LookbackRecorder` or any other SDK API.

Discussion

# INSTALLATION GUIDE

To use Participate inside your app:

  1. Add Lookback as a CocoaPod dependency to your project (or download and link the .framework and resource bundle manually).

  2. At lookback.io/dashboard, create a new iOS project, then configure it for "iOS app".

  3. Create a new app, and copy the "URL prefix".

  4. In Xcode > Your project > Your app target > Info > URL Types, create a new URL type, and paste the "URL prefix" into both "identifier" and "URL Schemes".

  5. In your app delegate, create an instance variable for a LookbackParticipate instance.

  6. from application:didFinishLaunchingWithOptions:, create the instance, and call setupFromDidFinishLaunchingWithApplicationWindow: with your main application window.

  7. In your app delegate, implement application:openURL:options: and application:continueUserActivity:restorationHandler:, and just forward the calls to LookbackParticipate.

You're done! Now whenever a user taps a Participate link targeted for your app, your app will launch and a research session will be started.

# EXAMPLE INTEGRATION

    class AppDelegate: UIResponder, UIApplicationDelegate {
        var window: UIWindow?
        var participate: LookbackParticipate!
        
        func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool
        {
            participate = LookbackParticipate()
            participate.setup(withApplicationWindow: self.window!)
            return true
        }

        func application(_ app: UIApplication, open url: URL, options: [UIApplicationOpenURLOptionsKey : Any] = [:]) -> Bool
        {
            return participate.startParticipation(from: url)
        }
    }
    

# USAGE FLOW

The usage flow, all the way from integration to completed research using the Participate SDK is as follows:

  1. You integrate the Participate SDK into your app by calling the public API of this class from your app delegate and configuring your info.plist. This has no visible effect on your app, but prepares it for future research.

  2. You distribute your app through AppStore, TestFlight or other means to your potential testers.

  3. You or your UX researcher creates a project on the Lookback Dashboard https://lookback.io/dashboard, and configures it to do research on your app.

  4. You send out a "Participate URL" to your test participant(s), probably over email

  5. Your participants tap the URL, which launches the Lookback web site with further instructions, telling them how to install your app and then start participating.

  6. When your participants tap the "Start participating!" button on that web site, your app is launched and the Participate UI is shown on top of your app, guiding your participants through the research flow. This flow might include setting up a live conversation, go through a fully guided remote self-test, or preparing for an in-house session.

  7. Your app and your user's interactions with it are recorded and/or live streamed to lookback.io, where your team can watch, communicate and collaborate around the collected video and research.



Methods

--canStartParticipationFromURL:

Just inspect the incoming URL and return whether it looks like a Lookback Participate URL or not. If you try to 'startParticipation...' an URL that passes this test, it will definitely show the Participate UI flow.

--setupWithApplicationWindow:

Call from your app delegate's -[application:didFinishLaunchingWithOptions:] to enable Participate in your app.

--startParticipationFromURL:

This method inspects the incoming URL, and if it looks like a Participate URL (as vended by the lookback.io web dashboard, either a "live" or a "self-test" link), it presents UI in an overlay window to guide the user through a research session.

-canStartParticipationFromURL:

Just inspect the incoming URL and return whether it looks like a Lookback Participate URL or not. If you try to 'startParticipation...' an URL that passes this test, it will definitely show the Participate UI flow.

-setupWithApplicationWindow:

Call from your app delegate's -[application:didFinishLaunchingWithOptions:] to enable Participate in your app.

-startParticipationFromURL:

This method inspects the incoming URL, and if it looks like a Participate URL (as vended by the lookback.io web dashboard, either a "live" or a "self-test" link), it presents UI in an overlay window to guide the user through a research session.


-canStartParticipationFromURL:


Just inspect the incoming URL and return whether it looks like a Lookback Participate URL or not. If you try to 'startParticipation...' an URL that passes this test, it will definitely show the Participate UI flow.

- (BOOL)canStartParticipationFromURL:(NSURL*)participateURL; 

See Also


-setupWithApplicationWindow:


Call from your app delegate's -[application:didFinishLaunchingWithOptions:] to enable Participate in your app.

- (void)setupWithApplicationWindow:(UIWindow*)applicationWindow; 
Discussion

If there are pending actions from last time the app ran (such as finishing an upload), this method will display this UI modally in a separate window.

Not calling this at app startup can lead to research not finishing or not uploading properly.:

See Also


-startParticipationFromURL:


This method inspects the incoming URL, and if it looks like a Participate URL (as vended by the lookback.io web dashboard, either a "live" or a "self-test" link), it presents UI in an overlay window to guide the user through a research session.

- (BOOL)startParticipationFromURL:(NSURL*)participateURL; 
Discussion

Call this method from your application's -application:openURL:options:. You can send in any URL, and it will only return YES/true if it is a proper Participate URL. If you handle other types of URLs in your app, make sure to handle Participate URLs first, like so:


        func application(_ app: UIApplication, open url: URL, options: [UIApplicationOpenURLOptionsKey : Any] = [:]) -> Bool
        {
            if participate.startParticipation(from: url) {
                return true
            }
            
            ... application's own URL handling goes here
        }
        

See Also


canStartParticipationFromURL:


Just inspect the incoming URL and return whether it looks like a Lookback Participate URL or not. If you try to 'startParticipation...' an URL that passes this test, it will definitely show the Participate UI flow.

- (BOOL)canStartParticipationFromURL:(NSURL*)participateURL; 

See Also


setupWithApplicationWindow:


Call from your app delegate's -[application:didFinishLaunchingWithOptions:] to enable Participate in your app.

- (void)setupWithApplicationWindow:(UIWindow*)applicationWindow; 
Discussion

If there are pending actions from last time the app ran (such as finishing an upload), this method will display this UI modally in a separate window.

Not calling this at app startup can lead to research not finishing or not uploading properly.:

See Also


startParticipationFromURL:


This method inspects the incoming URL, and if it looks like a Participate URL (as vended by the lookback.io web dashboard, either a "live" or a "self-test" link), it presents UI in an overlay window to guide the user through a research session.

- (BOOL)startParticipationFromURL:(NSURL*)participateURL; 
Discussion

Call this method from your application's -application:openURL:options:. You can send in any URL, and it will only return YES/true if it is a proper Participate URL. If you handle other types of URLs in your app, make sure to handle Participate URLs first, like so:


        func application(_ app: UIApplication, open url: URL, options: [UIApplicationOpenURLOptionsKey : Any] = [:]) -> Bool
        {
            if participate.startParticipation(from: url) {
                return true
            }
            
            ... application's own URL handling goes here
        }
        

See Also