TreasureData

@interface TreasureData : NSObject

The main interface for the SDK. All initialization and configuration (except retry parameters) could be done through here.

Minimal example:

 [TreasureData initializeWithApiKey:@"<your_write_only_api_key>"];

 [[TreasureData sharedInstance] addEvent:@{@"welcome": @"Hello world"}
                                database:@"my_db"
                                table:@"my_ios_events"];

 [[TreasureData sharedInstance] uploadEvents];

  • Inner client responsible for uploading events, automatically initialized. Additional parameters like request retrying could be configured here.

    Declaration

    Objective-C

    @property (readwrite, strong, nonatomic) TDClient *_Nullable client;

    Swift

    var client: TDClient? { get set }

  • The destination database for events that doesn’t specify one, default is td.

    Declaration

    Objective-C

    @property (readwrite, strong, nonatomic) NSString *_Nullable defaultDatabase;

    Swift

    var defaultDatabase: String? { get set }

  • The destination table for events that doesn’t specify one. Currently this also applied for automatically tracked events (if enabled): app lifecycle, IAP and audits, default is td_ios.

    Declaration

    Objective-C

    @property (readwrite, strong, nonatomic) NSString *_Nullable defaultTable;

    Swift

    var defaultTable: String? { get set }

  • The host to use for the Profile API Defaults to https://cdp.in.treasuredata.com

    Possible values: AWS East https://cdp.in.treasuredata.com AWS Tokyo https://cdp-tokyo.in.treasuredata.com AWS EU https://cdp-eu01.in.treasuredata.com IDCF https://cdp-idcf.in.treasuredata.com

    Declaration

    Objective-C

    @property (readwrite, strong, nonatomic) NSString *_Nullable cdpEndpoint;

    Swift

    var cdpEndpoint: String? { get set }

Initialization

  • Assign the target API endpoint, default is https://in.treasuredata.com. This have to be call before initializeWithApiKey(apiKey:), otherwise it won’t have effect.

    Declaration

    Objective-C

    + (void)initializeApiEndpoint:(NSString *_Nullable)apiEndpoint;

    Swift

    class func initializeApiEndpoint(_ apiEndpoint: String?)

    Parameters

    apiEndpoint

    for the in effect endpoint (+[TreasureData initializeApiEndpoint:]).

  • Encrypted the event data in the local persisted buffer. This should be called only once and prior to any addEvent... call.

    Declaration

    Objective-C

    + (void)initializeEncryptionKey:(NSString *_Nullable)encryptionKey;

    Swift

    class func initializeEncryptionKey(_ encryptionKey: String?)

  • Initialize TreasureData.sharedInstance with the current apiEndpoint configured via +[TreasureData initializeApiEndpoint:]

    Declaration

    Objective-C

    + (void)initializeWithApiKey:(NSString *_Nonnull)apiKey;

    Swift

    class func initialize(withApiKey apiKey: String)

    Parameters

    apiKey

    API Key (only requires write-only) for the in effect endpoint (+[TreasureData initializeApiEndpoint:]).

  • The default singleton SDK instance.

    You could create multiple instances that target different endpoints (and of course apiKey, and default database, table, etc.) with -[TreasureData initWithApiKey:], but mind that +[TreasureData initializeApiEndpoint:] is shared have to be called before -[TreasureData initWithApiKey:] to be affected.

    Declaration

    Objective-C

    + (instancetype _Nonnull)sharedInstance;

    Swift

    class func sharedInstance() -> Self

  • Construct a new TreasureData instance.

    Declaration

    Objective-C

    - (id _Nonnull)initWithApiKey:(NSString *_Nonnull)apiKey;

    Swift

    init(apiKey: String)

    Parameters

    apiKey

    for the in effect endpoint (+[TreasureData initializeApiEndpoint:]).

Tracking events

  • Track a new event

    Declaration

    Objective-C

    - (NSDictionary *_Nullable)addEvent:(NSDictionary *_Nonnull)record
                           database:(NSString *_Nonnull)database
                              table:(NSString *_Nonnull)table;

    Swift

    func addEvent(_ record: [AnyHashable : Any], database: String, table: String) -> [AnyHashable : Any]?

    Parameters

    record

    event data
    database

    the event’s destination database
    table

    the event’s destination table

  • Track a new event targets TreasureData.defaultDatabase

    Declaration

    Objective-C

    - (NSDictionary *_Nullable)addEvent:(NSDictionary *_Nonnull)record
                              table:(NSString *_Nonnull)table;

    Swift

    func addEvent(_ record: [AnyHashable : Any], table: String) -> [AnyHashable : Any]?

    Parameters

    record

    event data
    table

    the event’s destination table

  • Track a new event with status handlers.

    Note that addEvent... methods doesn’t involve network operations, failures here may indicate misconfigurations causing the event to not be inserted on the local buffer. For TreasureData instances that are purposedly disabled:

    This will silently return nil without invoking the onError handler.

    Declaration

    Objective-C

    - (NSDictionary *_Nullable)addEventWithCallback:(NSDictionary *_Nonnull)record
                                       database:(NSString *_Nonnull)database
                                          table:(NSString *_Nonnull)table
                                      onSuccess:
                                          (SuccessHander _Nullable)onSuccess
                                        onError:(ErrorHandler _Nullable)onError;

    Swift

    func addEvent(withCallback record: [AnyHashable : Any], database: String, table: String, onSuccess: SuccessHander?, onError: ErrorHandler? = nil) -> [AnyHashable : Any]?

    Parameters

    record

    event data
    database

    the event’s destination database
    table

    the event’s destination table
    onSuccess

    get called (on main thread) when the event successfuly inserted to the local buffer
    onError

    get called (on main thread) when the event failed to inserted to the local buffer, perfer ErrorHandler for possible error codes

  • Same as -[TreasureData addEventWithCallback:database:table:onSuccess:onError], targets the TreasureData.defaultDatabase.

    Declaration

    Objective-C

    - (NSDictionary *_Nullable)addEventWithCallback:(NSDictionary *_Nonnull)record
                                          table:(NSString *_Nonnull)table
                                      onSuccess:
                                          (SuccessHander _Nullable)onSuccess
                                        onError:(ErrorHandler _Nullable)onError;

    Swift

    func addEvent(withCallback record: [AnyHashable : Any], table: String, onSuccess: SuccessHander?, onError: ErrorHandler? = nil) -> [AnyHashable : Any]?

    Parameters

    record

    event data
    table

    the event’s destination table
    onSuccess

    get called (on main thread) when the event successfuly inserted to the local buffer
    onError

    get called (on main thread) when the event failed to inserted to the local buffer, perfer ErrorHandler for possible error codes

  • Same as -[TreasureData addEventWithCallback:database:table:onSuccess:onError], targets the TreasureData.defaultDatabase / TreasureData.defaultTable.

    Declaration

    Objective-C

    - (void)uploadEventsWithCallback:(SuccessHander _Nullable)onSuccess
                         onError:(ErrorHandler _Nullable)onError;

    Swift

    func uploadEvents(callback onSuccess: SuccessHander?, onError: ErrorHandler? = nil)

    Parameters

    onSuccess

    get called (on main thread) when the event successfuly uploaded to the configured endpoint. Notes that it doesn’t guarantee events to be successfully persisted to the remote database, it only indicates that the server accepted the request (without checking the validity of the events).
    onError

    get called (on main thread) when the event failed to inserted to the configured endpoint, perfer ErrorHandler for possible error codes

  • Same as -[TreasureData uploadEventWithCallback:onError:] but ignores the result status.

    Declaration

    Objective-C

    - (void)uploadEvents;

    Swift

    func uploadEvents()

Events' metadata

  • Automaticaly append td_uuid column for every events. The value is randomly generated and persisted, it is shared across app launches and events. Basically, it is used to prepresent for a unique app installation instance.

    This is disabled by default.

    Declaration

    Objective-C

    - (void)enableAutoAppendUniqId;

    Swift

    func enableAutoAppendUniqId()

  • Disable the auto appended td_uuid column.

    Declaration

    Objective-C

    - (void)disableAutoAppendUniqId;

    Swift

    func disableAutoAppendUniqId()

  • Permanently reset the appended td_uuid column to a different value. Note: this won’t reset the current buffered events before this call

    Declaration

    Objective-C

    - (void)resetUniqId;

    Swift

    func resetUniqId()

  • Disable these auto appended columns:

    • td_device, td_model: current these share a same value, extracted from UIDevice.currentDevice.model. Example: iPhone, iPad,…
    • td_os_version: Extracted from UIDevice.currentDevice.systemVersion. Example: 11.4.1, 12.1.4,…
    • td_os_type: Always iOS

    Declaration

    Objective-C

    - (void)enableAutoAppendModelInformation;

    Swift

    func enableAutoAppendModelInformation()

  • Disable the auto appended td_device, td_model, td_os_version, td_os_type columns.

    Declaration

    Objective-C

    - (void)disableAutoAppendModelInformation;

    Swift

    func disableAutoAppendModelInformation()

  • Automatically append these columns:

    • td_app_ver: extracted from main bundle’s CFBundleShortVersionString entry
    • td_app_ver_num: extracted from main bundle’s CFBundleVersion entry

    This is disabled by default.

    Declaration

    Objective-C

    - (void)enableAutoAppendAppInformation;

    Swift

    func enableAutoAppendAppInformation()

  • Disable these auto appended td_app_ver and td_app_ver_num column

    Declaration

    Objective-C

    - (void)disableAutoAppendAppInformation;

    Swift

    func disableAutoAppendAppInformation()

  • Automatically append these columns:

    • td_locale_country: ISO 3166-1’s code, extracted from NSLocale.currentLocale‘s NSLocaleCountryCode. Example: USA, AUS,…
    • td_locale_language: ISO 639-1's code, extracted fromNSLocal.currentLocal'sNSLocaleLanguageCode`. Example: es, en,…

    This is disabled by default.

    Declaration

    Objective-C

    - (void)enableAutoAppendLocaleInformation;

    Swift

    func enableAutoAppendLocaleInformation()

  • Disable the auto appended td_locale_country and td_locale_language columns.

    Declaration

    Objective-C

    - (void)disableAutoAppendLocaleInformation;

    Swift

    func disableAutoAppendLocaleInformation()

  • Automatically append the time value when the event is received on server. Disabled by default.

    Declaration

    Objective-C

    - (void)enableServerSideUploadTimestamp:(NSString *_Nonnull)columnName;

    Swift

    func enableServerSideUploadTimestamp(_ columnName: String)

    Parameters

    columnName

    The column to write the uploaded time value

  • Automatically append the time when the event is received on server. Disabled by default.

    This is disabled by default.

    Declaration

    Objective-C

    - (void)enableServerSideUploadTimestamp;

    Swift

    func enableServerSideUploadTimestamp()

  • Disable the uploading time column

    Declaration

    Objective-C

    - (void)disableServerSideUploadTimestamp;

    Swift

    func disableServerSideUploadTimestamp()

  • Automatically append a random and unique ID for each event. Disabled by default.

    Declaration

    Objective-C

    - (void)enableAutoAppendRecordUUID:(NSString *_Nonnull)columnName;

    Swift

    func enableAutoAppendRecordUUID(_ columnName: String)

    Parameters

    columnName

    The column to write the ID

  • Same as `-[TreasureData enableAutoAppendRecordUUID:], using record_uuid as the column name.

    Declaration

    Objective-C

    - (void)enableAutoAppendRecordUUID;

    Swift

    func enableAutoAppendRecordUUID()

  • Disable appending ID for each event.

    Declaration

    Objective-C

    - (void)disableAutoAppendRecordUUID;

    Swift

    func disableAutoAppendRecordUUID()

Session

  • Start to a new session for this TreasureData‘s instance

    Every subsequent events tracked from this instance will be appended a same random and unique value to td_session_id column. An additional event of `{td_session_event: start} will also be tracked, target the specified table and database.

    Declaration

    Objective-C

    - (void)startSession:(NSString *_Nonnull)table
            database:(NSString *_Nonnull)database;

    Swift

    func startSession(_ table: String, database: String)

    Parameters

    table

    Destination table for the td_session_event
    database

    Destination database for the td_session_event

  • Same as -[TreasureData startSession:database:], using TreasureData.defaultDatabase as the destination database for td_session_event.

    Declaration

    Objective-C

    - (void)startSession:(NSString *_Nonnull)table;

    Swift

    func startSession(_ table: String)

  • End this TresureData instance’s session. Track an additional event of {"td_session_event": "end"} to the specified database and table. Note that event if the instance’s session is ended, td_session_event still could be appended if the static session (+[TreasureData startSession]) is in effect.

    Declaration

    Objective-C

    - (void)endSession:(NSString *_Nonnull)table
          database:(NSString *_Nonnull)database;

    Swift

    func endSession(_ table: String, database: String)

    Parameters

    table

    Destination table for the td_session_event
    database

    Destination database for the td_session_event

  • Same as -[TreasureData endSession], using TreasureData.defaultDatbase as the destination database for td_session_event.

    Declaration

    Objective-C

    - (void)endSession:(NSString *_Nonnull)table;

    Swift

    func endSession(_ table: String)

  • Get this instance’s current session ID.

    Declaration

    Objective-C

    - (NSString *_Nullable)getSessionId;

    Swift

    func getSessionId() -> String?

  • Start a static session that is shared across TreasureData instances. Unlike instance’s session, there will be no td_session_event tracked.

    Declaration

    Objective-C

    + (void)startSession;

    Swift

    class func startSession()

  • End the current static session. Unlike instance’s session, there will be no td_session_event tracked.

    Declaration

    Objective-C

    + (void)endSession;

    Swift

    class func endSession()

  • Get the current static session ID.

    Declaration

    Objective-C

    + (NSString *_Nullable)getSessionId;

    Swift

    class func getSessionId() -> String?

  • Set the minimal time window that the static session stays alive.

    Declaration

    Objective-C

    + (void)setSessionTimeoutMilli:(long)to;

    Swift

    class func setSessionTimeoutMilli(_ to: Int)

    Parameters

    to

    The session timeout, default is 10 seconds

Automatically tracked events

  • Re-enable custom events collection if previously disabled

    Declaration

    Objective-C

    - (void)enableCustomEvent;

    Swift

    func enableCustomEvent()

  • Disable custom events collection (ones that called manually with addEvent...). This is a persistent setting so unless being re-enable with enableCustomEvent, all your tracked events with addEvent will be discarded. (Note that the app lifecycle events will still tracked, call disableAppLifecycleEvent to effectively disable all the event collections. This feature is supposed to be used for your users to opt-out of the tracking, a requirement for GDPR compliance.

    Declaration

    Objective-C

    - (void)disableCustomEvent;

    Swift

    func disableCustomEvent()

  • Whether the custom events collection is allowed or not. This is a persistent setting, which is able to set via enableCustomEvent or disableCustomEvent

    Declaration

    Objective-C

    - (BOOL)isCustomEventEnabled;

    Swift

    func isCustomEventEnabled() -> Bool

  • Enable tracking app lifecycle events. This setting is persited, default is disabled.

    Declaration

    Objective-C

    - (void)enableAppLifecycleEvent;

    Swift

    func enableAppLifecycleEvent()

  • Same as disableCustomEvent, this is supposed to be called for your users to opt-out of the automatic tracking.

    Declaration

    Objective-C

    - (void)disableAppLifecycleEvent;

    Swift

    func disableAppLifecycleEvent()

  • Whether the app lifecycle events collection is allowed or not This is a persistent setting, able to set through enableAppLifecycleEvent or disableAppLifecycleEvent

    Declaration

    Objective-C

    - (BOOL)isAppLifecycleEventEnabled;

    Swift

    func isAppLifecycleEventEnabled() -> Bool

  • Enable tracking SKPaymentTransactionStatePurchased event automatically. This is disabled by default. Unlike custom and app lifecycle events, this settings is not persisted.

    An example IAP event record:

     "td_ios_event": "TD_IOS_IN_APP_PURCHASE",
 "td_iap_transaction_identifier": "1000000514091400",
 "td_iap_transaction_date": "2019-03-28T08:44:12+07:00",
 "td_iap_quantity": 1,
 "td_iap_product_identifier": "com.yourcompany.yourapp.yourproduct", ,
 "td_iap_product_price": 0.99,
 "td_iap_product_localized_title": "Your Product Title",
 "td_iap_product_localized_description": "Your Product Description",
 "td_iap_product_currency_code": "USD",  // this is only available on iOS 10 and above

    Declaration

    Objective-C

    - (void)enableInAppPurchaseEvent;

    Swift

    func enableInAppPurchaseEvent()

  • Disable tracking IAP events

    Declaration

    Objective-C

    - (void)disableInAppPurchaseEvent;

    Swift

    func disableInAppPurchaseEvent()

  • Whether this TreasureData‘s instance tracking IAP events

    Declaration

    Objective-C

    - (BOOL)isInAppPurchaseEventEnabled;

    Swift

    func isInAppPurchaseEventEnabled() -> Bool

Personalization API

  • Fetch user segments from cdp endpoint. Callback with either a JSON serialized object or an error.

    Warning

    This will make a call to shared instance’s cdpEndpoint. Make sure you configure cdpEndpoint before using this method

    Declaration

    Objective-C

    - (void)fetchUserSegments:(nonnull NSArray<NSString *> *)audienceTokens
                     keys:(nonnull NSDictionary<NSString *, id> *)keys
                  options:
                      (nullable NSDictionary<TDRequestOptionsKey, id> *)options
        completionHandler:
            (void (^_Nonnull)(NSArray *_Nullable, NSError *_Nullable))handler;

    Swift

    func fetchUserSegments(tokens audienceTokens: [String], keys: [String : Any], options: [String : Any]? = nil, completionHandler handler: @escaping ([Any]?, Error?) -> Void)

    Parameters

    audienceTokens

    List of audience tokens. There must be at least one token.
    options

    Request options. For possible options, see TDRequestOptionsKey.
    handler

    Completion callback with either JSON object or an error. The callback will be called from the caller’s queue, or if there is no queue, default to main queue.

Misc.

  • Enable retrying on failed uploads. Already enabled by default.

    Use TreasureData.client for fine tuning retry’s configuration

    Declaration

    Objective-C

    - (void)enableRetryUploading;

    Swift

    func enableRetryUploading()

  • Do not attempt to retry on failed uploads.

    Use TreasureData.client for fine tuning retry’s configuration

    Declaration

    Objective-C

    - (void)disableRetryUploading;

    Swift

    func disableRetryUploading()

  • Event data will be compressed with zlib before uploading to server.

    Declaration

    Objective-C

    + (void)enableEventCompression;

    Swift

    class func enableEventCompression()

  • Event data will be uploaded in it’s full format.

    Declaration

    Objective-C

    + (void)disableEventCompression;

    Swift

    class func disableEventCompression()

  • Enable client logging. Disabled by default.

    Declaration

    Objective-C

    + (void)enableLogging;

    Swift

    class func enableLogging()

  • Disable client’s logging/

    Declaration

    Objective-C

    + (void)disableLogging;

    Swift

    class func disableLogging()

  • Enable trace logging

    Declaration

    Objective-C

    + (void)enableTraceLogging;

    Swift

    class func enableTraceLogging()

  • Disable trace logging

    Declaration

    Objective-C

    + (void)disableTraceLogging;

    Swift

    class func disableTraceLogging()

  • Undocumented

    Declaration

    Objective-C

    - (BOOL)isFirstRun;

    Swift

    func isFirstRun() -> Bool

  • Undocumented

    Declaration

    Objective-C

    - (void)clearFirstRun;

    Swift

    func clearFirstRun()

Deprecated

  • Deprecated

    Undocumented

    Declaration

    Objective-C

    - (void)event:(NSDictionary * _Nonnull)record database:(NSString * _Nonnull)database table:(NSString * _Nonnull)table DEPRECATED_ATTRIBUTE;

    Swift

    func event(_ record: [AnyHashable : Any], database: String, table: String)

  • Deprecated

    Undocumented

    Declaration

    Objective-C

    - (void)event:(NSDictionary * _Nonnull)record table:(NSString * _Nonnull)table DEPRECATED_ATTRIBUTE;

    Swift

    func event(_ record: [AnyHashable : Any], table: String)

  • Deprecated

    Undocumented

    Declaration

    Objective-C

    - (void)uploadWithBlock:(void (^ _Nonnull)(void))block DEPRECATED_ATTRIBUTE;

    Swift

    func upload(_ block: @escaping () -> Void)

  • Deprecated

    Undocumented

    Declaration

    Objective-C

    - (void)uploadEventsWithBlock:(void (^ _Nonnull)(void))block DEPRECATED_ATTRIBUTE;

    Swift

    func uploadEvents(_ block: @escaping () -> Void)

  • Deprecated

    Undocumented

    Declaration

    Objective-C

    - (void)setApiEndpoint:(NSString* _Nonnull)endpoint DEPRECATED_ATTRIBUTE;

    Swift

    func setApiEndpoint(_ endpoint: String)