/Localytics/LocalyticsSession.h

//  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