Cordova
Detailed technical documentation on RudderStack’s Cordova SDK to send events from your Cordova apps to various destinations.
Last updated
Was this helpful?
Detailed technical documentation on RudderStack’s Cordova SDK to send events from your Cordova apps to various destinations.
Last updated
Was this helpful?
Apache Cordova is an open-source, cross-platform application development framework.
The RudderStack Cordova SDK lets you track event data from your Cordova applications and send it to your specified destinations via RudderStack.
Check the GitHub codebase and the sample implementation to get a more hands-on understanding of the SDK.
To set up the Cordova SDK, follow these steps:
You will need to set up a RudderStack account.
Once signed up, set up a Cordova source in the dashboard. For more information, follow this guide. You should then see a Write Key for this source, as shown below:
You will also need a data plane URL. Follow this section for more information on the data plane URL and where to get it.
To add the Cordova SDK as a dependency, navigate to the root folder of your application and run the following command:
The Cordova SDK supports the device mode starting from version 1.3.0
.
After adding the SDK as a dependency, you need to set up the SDK.
Add the following code in the onDeviceReady()
function of your home page to initialize the SDK.
A sample Cordova SDK initialization is as shown:
Make sure you use the await
keyword with the initialize
call.
The setup
method has the following signature:
writeKey
string
Required
Your Cordova source writeKey
from the dashboard.
configuration
JSON Object
Optional
Contains the RudderStack client configuration.
options
JSON Object
Optional
Extra options to be pass along with the event.
Check the Configuring the RudderStack Client section below for detailed information on the parameters you can send in the configuration
object.
Check the Configuring the options object section below for detailed information on the parameters you can send in the options
object.
You can configure your RudderStack client by passing the following parameters in the configuration
object of your RudderClient.initialize()
call:
logLevel
RudderClient.LogLevel
Controls how much of the log you want to see from the Cordova SDK.
RudderClient.LogLevel.None
dataPlaneUrl
String
Your RudderStack Data Plane URL.
flushQueueSize
Integer
The number of events included in a batch request to the server.
30
dbThresholdCount
Integer
The number of events to be saved in the SQLite
database. Once the limit is reached, older events are deleted from the database.
10000
sleepTimeout
Integer
Minimum waiting time to flush the events to the server.
10 seconds
configRefreshInterval
Integer
RudderStack fetches the config after this time interval.
2
autoCollectAdvertId
Boolean
Determines if the SDK will collect the advertisement ID.
false
trackLifecycleEvents
Boolean
Determines if the SDK should capture the application lifecycle events automatically.
true
The identify
call lets you identify a visiting user and associate them with their actions. It also lets you record the traits about them like their name, email address, etc.
As a best practice, we recommend calling identify
at the start of every session or page load for logged-in users. This will ensure all their latest traits are captured in all the subsequent events.
A sample identify
call is as shown below:
The identify
method has the following signatures:
userId
string
Required
User identifier in your database.
traits
JSON Object
Optional
Information related to the user traits.
options
JSON Object
Optional
Extra options for the identify
event.
Check the Configuring the options object section below for detailed information on the parameters you can send in the options
object.
The track
call lets you record the user actions along with their associated properties. Each user action is called an event.
A sample track
event called Order Completed
using the Cordova SDK is shown below:
The track
method has the following signature:
name
String
Required
Contains the name of the event that you want to track.
properties
JSON Object
Optional
Contains the extra properties to be sent along with the event.
options
JSON Object
Optional
Contains the extra event options.
Check the Configuring the options object section below for detailed information on the parameters you can send in the options
object.
RudderStack automatically tracks the following optional events:
Application Installed
Application Opened
You can disable these events by sending the property trackLifecycleEvents
as false
within the configuration
object while initializing the RudderStack client. However, we highly recommend keeping them enabled.
The group
call lets you associate an identified user to a group - either a company, project, or a team, and record any custom traits or properties associated with that group.
A sample group
call is as shown:
The group
method has the following signatures:
groupId
string
Required
The organization ID with which you want to associate the user.
groupTraits
JSON Object
Optional
Any other property of the organization that you want to pass along with the call.
options
JSON Object
Optional
Extra options for the group
event.
Check the Configuring the options object section below for detailed information on the parameters you can send in the options
object.
The screen
call lets you record whenever your user views their mobile screen with any additional relevant information about the viewed screen.
A sample screen
call is shown below:
The screen
method has the following signature:
screenName
string
Required
Name of the viewed screen.
property
JSON Object
Optional
Extra properties that you want to pass along with the screen
call.
options
JSON Object
Optional
Extra options to be passed along with screen
event.
Check the Configuring the options object section below for detailed information on the parameters you can send in the options
object.
The alias
call lets you merge different identities of a known user.
alias
is an advanced method that lets you change the tracked user's ID explicitly. This method is useful when managing identities for some of the downstream destinations.
A sample alias
call is shown below:
The alias
method has the following signature:
newId
String
Required
The new userId
that you want to assign to the user.
options
JSON Object
Optional
Event level options.
Check the Configuring the options object section below for detailed information on the parameters you can send in the options
object.
For a detailed explanation of the alias
call, refer to the RudderStack API Specification guide.
You can use the reset
method to clear the persisted traits
from the identify
call. We recommend calling it during the Logout
operation.
A sample reset
call is as shown:
options
objectThe options
object can be sent along with all the above-mentioned API calls. It has the following signature:
externalIds
JSON Object
Optional
Each key within externalIds
object should define the type of external ID, and its value should be a String
or Integer
.
integrations
JSON Object
Optional
A sample options
object for an identify
event is as shown:
In the above snippet, the options
object is as follows:
RudderStack gives the users (e.g., an EU user) the ability to opt out of tracking any user activity until the user gives their consent. You can do this by leveraging RudderStack's optOut
API.
The optOut
API takes true
or false
as a Boolean value to enable or disable tracking user activities. This flag persists across the device reboots.
The following snippet highlights the use of the optOut
API to disable user tracking:
Once the user grants their consent, you can enable user tracking once again by using the optOut
API with false
as a parameter sent to it, as shown:
The optOut
API is available in the Cordova SDK starting from version 1.0.1
.
When sending events to a destination via the device mode, you can explicitly specify which events should be discarded or allowed to flow through - by whitelisting or blacklisting them.
Refer to the Client-side Event Filtering guide for more information on this feature.
RudderStack lets you send your event data only to the explicitly specified destinations and filtering out the rest. You can do this in one of the following two ways:
While initializing the Cordova SDK
While making the event calls
This approach is useful when you want to send the events to specific destinations across all the event calls made using the SDK.
A sample SDK initialization is shown below:
This approach is useful when you want to send particular events to specific destinations, or if you want to override the destinations specified during the SDK initialization for a particular event.
An example is shown below:
In the above example, the values of the screen
call are passed only to the Salesforce destination.
RudderStack uses the deviceId
as anonymousId by default. You can use the putAnonymousId
method to override the default anonymousId
, as shown:
RudderStack collects the advertisement ID only if autoCollectAdvertId
is set to true
during the SDK initialization, as shown:
To set the advertisement ID yourself, you can use the putAdvertisingId
method as shown:
In iOS, you need to call the putAdvertisingId
method before calling initialize
.
You can pass your device-token
for push notifications to be passed to the destinations which support the Push Notifications feature. RudderStack sets the token
under context.device.token
.
An example of setting the device-token
is as shown:
If you face any unexpected behavior while using the SDK, you can turn on the VERBOSE
or DEBUG
logging feature to determine out the issue.
You configure logging behavior of your SDK by sending the value of the logLevel
property of the configuration
object and pass it over to the initialize
call as shown below:
Once you set up a Cordova source in the RudderStack dashboard, you will be able to view the source Write Key, under the Overview section, as shown:
Refer to this section for more information on the data plane and how to get it.
For queries on any of the sections covered in this guide, you can contact us or start a conversation in our Slack community.
If you come across any issues while using the Cordova SDK, you can open a new issue on our GitHub Issues page.
Each key within the integrations
object should hold the display name of your desired destination. Its value should be a boolean
indicating whether you want to send that event or not. For more details check the section below.