TreasureData

Objective-C

@interface TreasureData : NSObject

Swift

class 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 (nonatomic, strong) 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 (nonatomic, strong) 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 (nonatomic, strong) 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 AWS Asia Pacific (Seoul) https://cdp-ap02.in.treasuredata.com AWS Asia Pacific (Tokyo) https://cdp-ap03.in.treasuredata.com

    Declaration

    Objective-C

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

    Swift

    var cdpEndpoint: String? { get set }

Initialization

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

  • Get UUID generated from TreasureData. The value will be set to td_uuid column for every events if enableAutoAppendUniqId is called.

    Declaration

    Objective-C

    - (NSString *_Nonnull)getUUID;

    Swift

    func getUUID() -> String

  • 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()

  • Automatically append the local time value when the event is added. Enabled by default.

    Declaration

    Objective-C

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

    Swift

    func enableAutoAppendLocalTimestamp(_ columnName: String)

    Parameters

    columnName

    The column to write the local time value

  • Automatically append the local time when the event is added. By default, the column’s name is “time”

    This is enabled by default.

    Declaration

    Objective-C

    - (void)enableAutoAppendLocalTimestamp;

    Swift

    func enableAutoAppendLocalTimestamp()

  • Disable automatically append the local time when the event is added.

    Declaration

    Objective-C

    - (void)disableAutoAppendLocalTimestamp;

    Swift

    func disableAutoAppendLocalTimestamp()

  • 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 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()

  • Automatically append device’s advertising identifer, a.k.a IDFA, using “td_maid” as the default column name.

    Declaration

    Objective-C

    - (void)enableAutoAppendAdvertisingIdentifier;

    Swift

    func enableAutoAppendAdvertisingIdentifier()

  • Automatically append device’s advertising identifer, a.k.a IDFA.

    Declaration

    Objective-C

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

    Swift

    func enableAutoAppendAdvertisingIdentifier(_ columnName: String)

    Parameters

    columnName

    The column to write the advertising identifier

  • Disable automatically append device’s advertising identifer, a.k.a IDFA.

    Declaration

    Objective-C

    - (void)disableAutoAppendAdvertisingIdentifier;

    Swift

    func disableAutoAppendAdvertisingIdentifier()

  • Automatically tracking device’s IP address in td_ip column. Disabled by default

    Declaration

    Objective-C

    - (void)enableAutoTrackingIP;

    Swift

    func enableAutoTrackingIP()

  • Disable automatically tracking device’s IP

    Declaration

    Objective-C

    - (void)disableAutoTrackingIP;

    Swift

    func disableAutoTrackingIP()

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?

  • Reset static session. This will force create a new session when static method startSession is called.

    Declaration

    Objective-C

    + (void)resetSessionId;

    Swift

    class func resetSessionId()

  • 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) async throws -> [Any]

    Parameters

    audienceTokens

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

    Profiles’ as specified in key column.
    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.

Default values

  • Set default value for key in all new events targeting database and table. When database and/or table parameters are nil, the nil parameter acts like a wild card that allows to set specified key value pair to new events added to any database (if database is nil) and/or to any table (if table is nil). For example, if you pass nil to both database and table parameters, all new events will have specified default value.

    Declaration

    Objective-C

    - (void)setDefaultValue:(nonnull id)value
                 forKey:(nonnull NSString *)key
               database:(nullable NSString *)database
                  table:(nullable NSString *)table;

    Swift

    func setDefaultValue(_ value: Any, forKey key: String, database: String?, table: String?)

    Parameters

    value

    default value for key
    key

    the event’s key that default value is set to, corresponding to column in table.
    database

    the database to set default value to. If nil, specified table of any database will have new events with the added default value.
    table

    the table to set default value to. If nil, any table of specified database will have new events with the added default value.

  • Get default value of key in all new events targeting database and table. See setDefaultValue:forKey:database:table: for logic setting database and table.

    Declaration

    Objective-C

    - (nullable id)defaultValueForKey:(nonnull NSString *)key
                         database:(nullable NSString *)database
                            table:(nullable NSString *)table;

    Swift

    func defaultValue(forKey key: String, database: String?, table: String?) -> Any?

    Parameters

    key

    the event’s key that default value is set to, corresponding to column in table.
    database

    the database to get default value from. If nil, get default value of specified table of any database.
    table

    the table to get default value from. If nil, get default value of any table of specified database.

    Return Value

    default value for key for events targeting database and table.

  • Remove default value of key in all new events targeting database and table. See setDefaultValue:forKey:database:table: for logic setting database and table.

    Declaration

    Objective-C

    - (void)removeDefaultValueForKey:(nonnull NSString *)key
                        database:(nullable NSString *)database
                           table:(nullable NSString *)table;

    Swift

    func removeDefaultValue(forKey key: String, database: String?, table: String?)

    Parameters

    key

    the event’s key that default value is set to, corresponding to column in table.
    database

    the database to remove default value from. If nil, specified table of any database will have new events without the default value.
    table

    the table to remove default value from. If nil, any table of specified database will have new events without the default value.

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() async

  • Deprecated

    Undocumented

    Declaration

    Objective-C

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

    Swift

    func uploadEvents() async

  • Deprecated

    Undocumented

    Declaration

    Objective-C

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

    Swift

    func setApiEndpoint(_ endpoint: String)