//
|
// TFSScribe.h
|
// TFSScribe
|
//
|
// Created by Tanner Oakes on 10/10/14.
|
// Copyright (c) 2014 Twitter. All rights reserved.
|
//
|
|
#import <Foundation/Foundation.h>
|
|
#ifndef NS_DESIGNATED_INITIALIZER
|
#define NS_DESIGNATED_INITIALIZER __attribute((objc_designated_initializer))
|
#endif
|
|
FOUNDATION_EXTERN NSString *const TFSScribeDebugPreferencesKey;
|
|
FOUNDATION_EXTERN NSString *const TFSScribeEventNotification; // Triggered when the scribe API call returns
|
FOUNDATION_EXTERN NSString *const TFSScribeFlushNotification; // Triggered after scribe flush
|
FOUNDATION_EXTERN NSString *const TFSScribeFlushTokenInfoKey; // Key in userInfo dictionary corresponding to the token used in the flush request.
|
|
FOUNDATION_EXTERN const NSInteger TFSScribeServiceUpdateValue;
|
|
/**
|
* Result of handling outgoing scribe events.
|
*/
|
typedef NS_ENUM(NSUInteger, TFSScribeServiceRequestDisposition) {
|
/**
|
* Indicates that the outgoing events were handled successfully.
|
*/
|
TFSScribeServiceRequestDispositionSuccess,
|
/**
|
* Indicates that handling failed due to a client side problem, such as a network
|
* timeout or the request being cancelled.
|
*/
|
TFSScribeServiceRequestDispositionClientError,
|
/**
|
* Indicates that handling failed due to the server rejecting the sent data.
|
*/
|
TFSScribeServiceRequestDispositionServerError,
|
};
|
|
/**
|
* Object representing a scribe event. These methods must be thread safe.
|
*/
|
@protocol TFSScribeEventParameters <NSObject>
|
|
/**
|
* Binary representation of the scribe event. This is what will be kept in
|
* the store and returned when flush is called.
|
*/
|
- (NSData *)data;
|
/**
|
* Dictionary representation of the event used for logging purposes.
|
*/
|
- (NSDictionary *)dictionaryRepresentation;
|
/**
|
* User ID of event
|
*/
|
- (NSString *)userID;
|
|
@end
|
|
@class TFSScribe;
|
|
@protocol TFSScribeErrorDelegate <NSObject>
|
|
/**
|
* Scribe will call this method on an arbitrary queue if it encounters
|
* an internal error.
|
*/
|
- (void)scribeService:(TFSScribe *)service didEncounterError:(NSError *)error;
|
|
@end
|
|
typedef void (^TFSScribeRequestBatchedImpressionEventBlock)(id<TFSScribeEventParameters> scribeEventParameters);
|
typedef void (^TFSScribeRequestCompletionBlock)(TFSScribeServiceRequestDisposition disposition);
|
|
@protocol TFSScribeRequestHandler <NSObject>
|
|
/**
|
* TFSScribe will call this method once it has prepared all of the outgoing events.
|
* This method will be called on a background queue.
|
*
|
* @param outgoingEvents Prepared outgoing events
|
* @param userID User ID to send events for. Must not be nil.
|
* @param completionHandler Execute the completion block once the events have been handled with the appropriate disposition. The completion block can be executed on any queue.
|
*/
|
- (void)handleScribeOutgoingEvents:(NSString *)outgoingEvents userID:(NSString *)userID completionHandler:(TFSScribeRequestCompletionBlock)completionHandler;
|
|
@optional
|
|
/**
|
* When flushing a user ID, this method will be called with an array of impressions
|
* for you to batch. After the method is executed, the impressions will be deleted
|
* from the store. If this method is not implemented, impressions will still be
|
* deleted.
|
*
|
* @param impressions Array of TFSScribeImpressions objects.
|
* @param batchedHandler Call the batchedHandler block for each event data you generate from the impressions.
|
*/
|
- (void)handleImpressionsBatch:(NSArray *)impressions batchedImpressionHandler:(TFSScribeRequestBatchedImpressionEventBlock)batchedHandler;
|
|
@end
|
|
@interface TFSScribe : NSObject
|
|
@property (nonatomic, weak) id<TFSScribeErrorDelegate> errorDelegate;
|
|
+ (BOOL)isDebugEnabled;
|
+ (void)setDebugEnabled:(BOOL)enabled;
|
|
/**
|
* Init the scribe.
|
*
|
* @param storeURL File URL to store the persisted data. Pass nil to use an in-memory store.
|
*/
|
- (instancetype)initWithStoreURL:(NSURL *)storeURL;
|
|
/**
|
* Init the scribe.
|
*
|
* @param storeURL File URL to store the persisted data. Pass nil to use an in-memory store.
|
* @param modelURL File URL to the location of the mom on disk. Not necessary if you are using the framework, or if your mom is in the mainBundle.
|
*/
|
- (instancetype)initWithStoreURL:(NSURL *)storeURL modelURL:(NSURL *)modelURL NS_DESIGNATED_INITIALIZER;
|
|
/**
|
* Opens the scribe asynchronously.
|
*/
|
- (void)open;
|
|
/**
|
* Opens the scribe asynchronously.
|
*
|
* @param startBlock Block will be executed on a background queue immediately prior to opening. Can be nil.
|
* @param completionBlock Block will be executed on a background queue immediately after opening. Can be nil.
|
*/
|
- (void)openWithStartBlock:(dispatch_block_t)startBlock completionBlock:(dispatch_block_t)completionBlock;
|
|
/**
|
* Closes the scribe asynchronously.
|
*/
|
- (void)close;
|
|
/**
|
* Closes the scribe asynchronously.
|
*
|
* @param startBlock Block will be executed on a background queue immediately prior to closing. Can be nil.
|
* @param completionBlock Block will be executed on a background queue immediately after closing. Can be nil.
|
*/
|
- (void)closeWithStartBlock:(dispatch_block_t)startBlock completionBlock:(dispatch_block_t)completionBlock;
|
|
/**
|
* Suspend the scribe's internal background queue. This could be used to improve scrolling performance on older devices.
|
*/
|
- (void)suspend;
|
/**
|
* Resume the scribe's internal background queue.
|
*/
|
- (void)resume;
|
|
/**
|
* Flush all events for the given userID. If no events or impressions exist
|
*
|
* @param userID User ID to flush events for. Must not be nil.
|
* @param requestHandler Once the events have been prepared, the request handler will be called to handle the events. Must not be nil.
|
*/
|
- (void)flushUserID:(NSString *)userID requestHandler:(id<TFSScribeRequestHandler>)requestHandler;
|
|
/**
|
* Flush all events for the given userID.
|
*
|
* @param userID User ID to flush events for. Must not be nil.
|
* @param token A token to be included with notification userInfo dictionaries.
|
* @param requestHandler Once the events have been prepared, the request handler will be called to handle the events. Must not be nil.
|
*/
|
- (void)flushUserID:(NSString *)userID token:(NSString *)token requestHandler:(id<TFSScribeRequestHandler>)requestHandler;
|
|
/**
|
* Delete all events for the given userID. Events for user ID of 0 (anonymous user) will not be deleted.
|
*/
|
- (void)deleteUserID:(NSString *)userID;
|
|
/**
|
* Schedule an event to be added to scribe.
|
*/
|
- (void)enqueueEvent:(id<TFSScribeEventParameters>)eventParameters;
|
|
/**
|
* Schedule an impression to be added to scribe.
|
*/
|
- (void)enqueueImpression:(NSData *)contentData eventName:(NSString *)eventName query:(NSString *)query clientVersion:(NSString *)clientVersion userID:(NSString *)userID;
|
|
#if UIAUTOMATION
|
- (void)clearScribeDatabase;
|
#endif
|
|
@end
|
