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];
-
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 }
-
Assign the target API endpoint, default is
https://in.treasuredata.com
. This have to be call beforeinitializeWithApiKey(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 currentapiEndpoint
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:]
).
-
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. ForTreasureData
instances that are purposedly disabled:This will silently return
nil
without invoking theonError
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 theTreasureData.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 theTreasureData.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()
-
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 callDeclaration
Objective-C
- (void)resetUniqId;
Swift
func resetUniqId()
-
Disable these auto appended columns:
td_device
,td_model
: current these share a same value, extracted fromUIDevice.currentDevice.model
. Example:iPhone
,iPad
,…td_os_version
: Extracted fromUIDevice.currentDevice.systemVersion
. Example:11.4.1
,12.1.4
,…td_os_type
: AlwaysiOS
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’sCFBundleShortVersionString
entrytd_app_ver_num
: extracted from main bundle’sCFBundleVersion
entry
This is disabled by default.
Declaration
Objective-C
- (void)enableAutoAppendAppInformation;
Swift
func enableAutoAppendAppInformation()
-
Disable these auto appended
td_app_ver
andtd_app_ver_num
columnDeclaration
Objective-C
- (void)disableAutoAppendAppInformation;
Swift
func disableAutoAppendAppInformation()
-
Automatically append these columns:
td_locale_country
: ISO 3166-1’s code, extracted fromNSLocale.currentLocale
‘sNSLocaleCountryCode
. Example:USA
,AUS
,…td_locale_language: ISO 639-1's code, extracted from
NSLocal.currentLocal's
NSLocaleLanguageCode`. Example:es
,en
,…
This is disabled by default.
Declaration
Objective-C
- (void)enableAutoAppendLocaleInformation;
Swift
func enableAutoAppendLocaleInformation()
-
Disable the auto appended
td_locale_country
andtd_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()
-
Start to a new session for this
TreasureData
‘s instanceEvery 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:]
, usingTreasureData.defaultDatabase
as the destination database fortd_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]
, usingTreasureData.defaultDatbase
as the destination database fortd_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 notd_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
-
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 withenableCustomEvent
, all your tracked events withaddEvent
will be discarded. (Note that the app lifecycle events will still tracked, calldisableAppLifecycleEvent
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
ordisableCustomEvent
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
ordisableAppLifecycleEvent
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 eventsDeclaration
Objective-C
- (BOOL)isInAppPurchaseEventEnabled;
Swift
func isInAppPurchaseEventEnabled() -> Bool
-
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 methodDeclaration
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.
-
Enable retrying on failed uploads. Already enabled by default.
Use
TreasureData.client
for fine tuning retry’s configurationDeclaration
Objective-C
- (void)enableRetryUploading;
Swift
func enableRetryUploading()
-
Do not attempt to retry on failed uploads.
Use
TreasureData.client
for fine tuning retry’s configurationDeclaration
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
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)