/Localytics/LocalyticsSession.h
C Header | 201 lines | 37 code | 19 blank | 145 comment | 0 complexity | 93c8fae4dd8f7b6d59c111e53c7b8dff MD5 | raw file
- // LocalyticsSession.h
- // Copyright (C) 2009 Char Software Inc., DBA Localytics
- //
- // This code is provided under the Localytics Modified BSD License.
- // A copy of this license has been distributed in a file called LICENSE
- // with this source code.
- //
- // Please visit www.localytics.com for more information.
-
- #import <UIKit/UIKit.h>
-
- // Set this to true to enable localytics traces (useful for debugging)
- #define DO_LOCALYTICS_LOGGING false
-
- /*!
- @class LocalyticsSession
- @discussion The class which manages creating, collecting, & uploading a Localytics session.
- Please see the following guides for information on how to best use this
- library, sample code, and other useful information:
- <ul>
- <li><a href="http://wiki.localytics.com/index.php?title=Developer's_Integration_Guide">Main Developer's Integration Guide</a></li>
- </ul>
-
- <strong>Best Practices</strong>
- <ul>
- <li>Instantiate the LocalyticsSession object in applicationDidFinishLaunching.</li>
- <li>Open your session and begin your uploads in applicationDidFinishLaunching. This way the
- upload has time to complete and it all happens before your users have a
- chance to begin any data intensive actions of their own.</li>
- <li>Close the session in applicationWillTerminate, and in applicationDidEnterBackground.</li>
- <li>Resume the session in applicationWillEnterForeground.</li>
- <li>Do not call any Localytics functions inside a loop. Instead, calls
- such as <code>tagEvent</code> should follow user actions. This limits the
- amount of data which is stored and uploaded.</li>
- <li>Do not use multiple LocalticsSession objects to upload data with
- multiple application keys. This can cause invalid state.</li>
- </ul>
-
- @author Localytics
- @version 2.0
- */
- @interface LocalyticsSession : NSObject {
-
- BOOL _hasInitialized; // Whether or not the session object has been initialized.
- BOOL _isSessionOpen; // Whether or not this session has been opened.
- float _backgroundSessionTimeout; // If an App stays in the background for more
- // than this many seconds, start a new session
- // when it returns to foreground.
- @private
- #pragma mark Member Variables
- NSString *_sessionUUID; // Unique identifier for this session.
- NSString *_applicationKey; // Unique identifier for the instrumented application
- NSTimeInterval _lastSessionStartTimestamp; // The start time of the most recent session.
- NSDate *_sessionResumeTime; // Time session was started or resumed.
- NSDate *_sessionCloseTime; // Time session was closed.
- NSMutableString *_newFlowEvents; // Comma-delimited list of app screens and events tagged during this
- // session that have NOT been staged for upload.
- NSMutableString *_oldFlowEvents; // App screens and events tagged during this session that HAVE been staged
- // for upload.
- NSMutableString *_screens; // Comma-delimited list of screens tagged during this session.
- NSTimeInterval _sessionActiveDuration; // Duration that session open.
- BOOL _sessionHasBeenOpen; // Whether or not this session has ever been open.
- }
-
- @property BOOL isSessionOpen;
- @property BOOL hasInitialized;
- @property float backgroundSessionTimeout;
-
- #pragma mark Public Methods
- /*!
- @method sharedLocalyticsSession
- @abstract Accesses the Session object. This is a Singleton class which maintains
- a single session throughout your application. It is possible to manage your own
- session, but this is the easiest way to access the Localytics object throughout your code.
- The class is accessed within the code using the following syntax:
- [[LocalyticsSession sharedLocalyticsSession] functionHere]
- So, to tag an event, all that is necessary, anywhere in the code is:
- [[LocalyticsSession sharedLocalyticsSession] tagEvent:@"MY_EVENT"];
- */
- + (LocalyticsSession *)sharedLocalyticsSession;
-
- /*!
- @method LocalyticsSession
- @abstract Initializes the Localytics Object. Not necessary if you choose to use startSession.
- @param applicationKey The key unique for each application generated at www.localytics.com
- */
- - (void)LocalyticsSession:(NSString *)appKey;
-
- /*!
- @method startSession
- @abstract An optional convenience initialize method that also calls the LocalyticsSession, open &
- upload methods. Best Practice is to call open & upload immediately after Localytics Session when loading an app,
- this method fascilitates that behavior.
- It is recommended that this call be placed in <code>applicationDidFinishLaunching</code>.
- @param applicationKey The key unique for each application generated
- at www.localytics.com
- */
- - (void)startSession:(NSString *)appKey;
-
- /*!
- @method setOptIn
- @abstract (OPTIONAL) Allows the application to control whether or not it will collect user data.
- Even if this call is used, it is necessary to continue calling upload(). No new data will be
- collected, so nothing new will be uploaded but it is necessary to upload an event telling the
- server this user has opted out.
- @param optedIn True if the user is opted in, false otherwise.
- */
- - (void)setOptIn:(BOOL)optedIn;
-
- /*!
- @method isOptedIn
- @abstract (OPTIONAL) Whether or not this user has is opted in or out. The only way they can be
- opted out is if setOptIn(false) has been called before this. This function should only be
- used to pre-populate a checkbox in an options menu. It is not recommended that an application
- branch based on Localytics instrumentation because this creates an additional test case. If
- the app is opted out, all localytics calls will return immediately.
- @result true if the user is opted in, false otherwise.
- */
- - (BOOL)isOptedIn;
-
- /*!
- @method open
- @abstract Opens the Localytics session. Not necessary if you choose to use startSession.
- The session time as presented on the website is the time between <code>open</code> and the
- final <code>close</code> so it is recommended to open the session as early as possible, and close
- it at the last moment. The session must be opened before any tags can
- be written. It is recommended that this call be placed in <code>applicationDidFinishLaunching</code>.
- <br>
- If for any reason this is called more than once every subsequent open call
- will be ignored.
- */
- - (void)open;
-
- /*!
- @method resume
- @abstract Resumes the Localytics session. When the App enters the background, the session is
- closed and the time of closing is recorded. When the app returns to the foreground, the session
- is resumed. If the time since closing is greater than BACKGROUND_SESSION_TIMEOUT, (15 seconds
- by default) a new session is created, and uploading is triggered. Otherwise, the previous session
- is reopened.
- */
- - (void)resume;
-
- /*!
- @method close
- @abstract Closes the Localytics session. This should be called in
- <code>applicationWillTerminate</code>.
- <br>
- If close is not called, the session will still be uploaded but no
- events will be processed and the session time will not appear. This is
- because the session is not yet closed so it should not be used in
- comparison with sessions which are closed.
- */
- - (void)close;
-
- /*!
- @method tagEvent
- @abstract Allows a session to tag a particular event as having occurred. For
- example, if a view has three buttons, it might make sense to tag
- each button click with the name of the button which was clicked.
- For another example, in a game with many levels it might be valuable
- to create a new tag every time the user gets to a new level in order
- to determine how far the average user is progressing in the game.
- <br>
- <strong>Tagging Best Practices</strong>
- <ul>
- <li>DO NOT use tags to record personally identifiable information.</li>
- <li>The best way to use tags is to create all the tag strings as predefined
- constants and only use those. This is more efficient and removes the risk of
- collecting personal information.</li>
- <li>Do not set tags inside loops or any other place which gets called
- frequently. This can cause a lot of data to be stored and uploaded.</li>
- </ul>
- <br>
- See the tagging guide at: http://wiki.localytics.com/
- @param event The name of the event which occurred.
- */
- - (void)tagEvent:(NSString *)event;
-
- - (void)tagEvent:(NSString *)event attributes:(NSDictionary *)attributes;
-
- - (void)tagEvent:(NSString *)event attributes:(NSDictionary *)attributes reportAttributes:(NSDictionary *)reportAttributes;
-
- /*!
- @method tagScreen
- @abstract Allows tagging the flow of screens encountered during the session.
- @param screen The name of the screen
- */
- - (void)tagScreen:(NSString *)screen;
-
- /*!
- @method upload
- @abstract Creates a low priority thread which uploads any Localytics data already stored
- on the device. This should be done early in the process life in order to
- guarantee as much time as possible for slow connections to complete. It is also reasonable
- to upload again when the application is exiting because if the upload is cancelled the data
- will just get uploaded the next time the app comes up.
- */
- - (void)upload;
-
- @end