Treasure Data Mobiles SDKs Plugin for Cordova
npm install td-cordova-sdkYou can see more detailed documentation in repositories for td-android-sdk and td-ios-sdk
cordova plugin add td-cordova-sdk
Usage
After installing the plugin, you can access the methods through
namespace.Configuration
`javascript
TreasureDataPlugin.setup({
apiEndpoint: 'https://us01.records.in.treasuredata.com', // Or other supported endpoints
encryptionKey: 'xxxxx',
apiKey: 'xxxxx', /// You should use write only api key
defaultDatabase: 'default_database',
defaultTable: 'default_table_name',
cdpEndpoint: 'https://cdp.in.treasuredata.com' // Or other cdp endpoints
})
`Add an event to local buffer
You can add custom events to a specific database and table. If database param is not specified, configuration in TreasureDataPlugin.setup({...}) will be used instead.
Specify the database and table to which you want to import the events. The total length of database and table must be shorter than 129 characters.
`javascript
const customEvent = {event: 'Custom event', data: new Date().getSeconds()};
TreasureDataPlugin.addEvent(customEvent, 'table', 'database');
// or
TreasureDataPlugin.addEvent(customEvent, 'table');
`Or if you need to know when
is successful or has failed, use addEventWithCallback instead. You can pass null or undefined as database param and defaultDatabase configuration in TreasureDataPlugin.setup({...}) will be used instead.
`javascript
const customEvent = {event: 'Custom event', data: new Date().getSeconds()};
TreasureDataPlugin.addEventWithCallback(customEvent, 'table', 'database', () => {
console.log('Add Event Successfully');
}, (errorCode, errorMessage) => {
console.log('Add Event Failed', errorCode, errorMessage);
});
`Upload buffered events to TreasureData
You can upload all buffered events to Treasure Data at anytime with function
`javascript
TreasureDataPlugin.uploadEvents();
`Or if you need to know when
is successful or has failed, use uploadEventsWithCallback instead.
`javascript
TreasureDataPlugin.uploadEventsWithCallback(() => {
console.log('Upload events successfully')
}, (errorCode, errorMessage) => {
console.log('Failed to upload events', errorCode, errorMessage);
});
`Custom Events
Add and upload custom events are enabled by default. However you can disable and enable this feature at any time using:
javascript
TreasureDataPlugin.enableCustomEvent();
`
To disable custom events
javascript
TreasureDataPlugin.disableCustomEvent();
`(Android only) Track app lifecycle events automatically
This feature is only available in Android. App lifecycle event tracking is optional and not enable by default. You can track app lifecycle events automatically using:
javascript
TreasureDataPlugin.enableAppLifecycleEvent();
`
To disable tracking app lifecycle events:
javascript
TreasureDataPlugin.disableAppLifecycleEvent();
`
To check if tracking app lifecycle events is enabled:
javascript
TreasureDataPlugin.isAppLifecycleEventEnabled((enabled) => {
console.log('Tracking app lifecycle event is enabled?', enabled ? 'yes' : 'no');
})
`Track in app purchase events automatically
You don't need to check for platform when calling this feature's APIs, they will simply be no-op.
In app purchase event tracking is optional and not enable by default. To track in app purchase events automatically, you only need to add a line of code:
javascript
TreasureDataPlugin.enableInAppPurchaseEvent();
`
To disable tracking in app purchase events:
javascript
TreasureDataPlugin.disableInAppPurchaseEvent();
`
To check if tracking in app purchase events is enabled:
javascript
TreasureDataPlugin.isInAppPurchaseEventEnabled((enabled) => {
console.log('Tracking in app purchase event is enabled?', enabled ? 'yes' : 'no');
})
`Adding UUID of the device to each event automatically
UUID of the device will be added to each event automatically if you call . This value won't change until the application is uninstalled.
`javascript
TreasureDataPlugin.enableAutoAppendUniqId();
`
To disable adding UUID of device to each event automatically:
javascript
TreasureDataPlugin.disableAutoAppendUniqId();
`
To reset UUID of device
javascript
TreasureDataPlugin.resetUniqId();
`Adding an UUID to each event record automatically
UUID will be added to each event record automatically if you call . Each event has different UUID.
`javascript
TreasureDataPlugin.enableAutoAppendRecordUUID();
`
To disable adding record UUID to each event automatically:
javascript
TreasureDataPlugin.disableAutoAppendRecordUUID();
`Adding Advertising Id to each event record automatically
Advertising Id will be added to each event record automatically if you call .In Android, you must install Google Play Service Ads (Gradle
com.google.android.gms:play-services-ads) as a dependency for this feature to work.In iOS, you must link Ad Support framework in Link Binary With Libraries build phase for this feature to work.
User must also not turn on Limit Ad Tracking feature in their device, otherwise, Treasure Data will not attach Advertising Id to the record. Due to asynchronous nature of getting Advertising Id, after
enableAutoAppendAdvertisingIdentifier method called, it may take some time for Advertising Id to be available to be added to the record. However, Treasure Data does cache the Advertising Id in order to add to the next event without having to wait for the fetch Advertising Id task to complete.
`javascript
TreasureDataPlugin.enableAutoAppendAdvertisingIdentifier();
// Or specify custom column
TreasureDataPlugin.enableAutoAppendAdvertisingIdentifier('custom_aaid_column');
`
To disable adding Advertising Id:
javascript
TreasureDataPlugin.disableAutoAppendAdvertisingIdentifier();
`Adding device model information to each event automatically
To add device model information to each event automatically
javascript
TreasureDataPlugin.enableAutoAppendModelInformation();
`
To disable:
javascript
TreasureDataPlugin.disableAutoAppendModelInformation();
`Adding application package version information to each event automatically
To add application version information to each event automatically
javascript
TreasureDataPlugin.enableAutoAppendAppInformation();
`
To disable:
javascript
TreasureDataPlugin.disableAutoAppendAppInformation();
`Adding locale configuration information to each event automatically
To add locale configuration information to each event automatically
javascript
TreasureDataPlugin.enableAutoAppendLocaleInformation();
`
To disable:
javascript
TreasureDataPlugin.disableAutoAppendLocaleInformation();
`Start/End session
Call to start tracking a session
`javascript
TreasureDataPlugin.startSession(sessionTable, sessionDatabase);
`
Call to end tracking current session
`javascript
TreasureDataPlugin.endSession(sessionTable, sessionDatabase);
`Profile API
This feature is not enabled on accounts by default, please contact support for more information. Important! You must set cdpEndpoint property of TreasureData's sharedInstance. Usage example:javascript
var plugin = cordova.plugins.TreasureDataPlugin;
function success(response) {
/* response format => [
{
"segments": ["segment_id"],
"attributes": {
"age": ##,
"td_client_id": "xxxxxxxxxxxxx"
},
"audienceId": "audience_id",
"key": { "name": "user_id", "value": "xxxxxxx" }
},
{
"segments": ["segment_id", "segment_id"],
"attributes": {
"im_segments": "xxxxxxxxxxxx",
"work_style_per_family": "xxxxxxxx"
},
"audienceId": "audience_id",
"key": {
"name": "td_client_id",
"value": "xxxxxxxxxxxxx"
}
}
] */ // yay
}
function error() {
// nay
}
plugin.fetchUserSegments(
["audience_id","audience_id"],
{
user_id: "xxxxx",
td_client_id: "xxxxx"
},
success,
error
);
`Default values
Set a default value if you want an event added to a table, a database, or any table or database to automatically set value for a key.
If you have multiple default values set to the same key, newly added event will have the default value applied and override in following order:
1. Default value targeting all tables and databases will be applied first.
2. Default value targeting all tables in a database will then be applied.
3. Default value targeting the table to which the event is added will then be applied.
4. Default value targeting the table and database to which the event is added will then be applied.
5. Finally, if the event has a value for the key, that value will override all default values.
To set default value:
javascript
TreasureDataPlugin.setDefaultValue("value", "key"); // Targeting all databases and tables
TreasureDataPlugin.setDefaultValue("value", "key", "database_name"); // Targeting all tables of database "database_name"
TreasureDataPlugin.setDefaultValue("value", "key", null, "table_name"); // Targeting all tables with "table_name" of any database
TreasureDataPlugin.setDefaultValue("value", "key", "database_name", "table_name"); // Targeting table "table_name" of database "database_name"
`To get default value:
javascript
// Get default value for key targeting database "database_name" and table "table_name".
TreasureDataPlugin.defaultValue("key", "database_name", "table_name", (defaultValue) => {
console.log('Default Value', defaultValue);
});
`To remove default value:
javascript
// Only remove default values targeting database "database_name" and table "table_name".
TreasureDataPlugin.removeDefaultValue("key", "database_name", "table_name");
`Enable/Disable debug log
To enable debug log
javascript
TreasureDataPlugin.enableLogging();
`
To disable:
javascript
TreasureDataPlugin.disableLogging();
`Enable/Disable retry uploading
To enable retry uploading
javascript
TreasureDataPlugin.enableRetryUploading();
`
To disable:
javascript
TreasureDataPlugin.disableRetryUploading();
``