analytics-web3

# Spock Analytics SDK Spock analytics SDK `analytics-web3` is a Javascript module to collect and log all the data and events of DApp for analytics. ## Spock Spock aims to accelerate your growth by tracking & analyzing crucial and opportunity-centric metrics that will help you to amplify your growth and reach to the right customer segment. ## Table of contents - [Spock Analytics SDK](#spock-analytics-sdk) - [About Spock](#spock) - [Table of contents](#table-of-contents) - [Installation](#installation) - [Usage](#usage) - [API](#api) - [Initialization](#web3analyticsinitoptions) - [Wallet provider](#web3analyticswalletproviderprovider) - [Wallet connection](#web3analyticstrackwalletconnectionwallettypeaccountchainid) - [Page view](#web3analyticstrackpageviewpathnamesearch) - [Opt out](#web3analyticsoptouttrackingexpiration) - [Opt in](#web3analyticsoptintrackingexpiration) - [Opt out status](#web3analyticshasoptedouttracking) - [Widget On-click](#web3analyticswidgetonclickmethod) - [Supporting wallets](#supporting-wallets) - [Datapoints](#datapoints) - [License](#license) - [Demo](#demo) - [Documentation](#documentation) - [Credits](#credits) ## Installation Install analytics-web3 sdk by using npm ```bash npm install --save analytics-web3 ``` or yarn ```bash yarn add analytics-web3 ``` ## Usage Initialize and track wallet connection and transactions by passing web3 provider. ```js import Web3Analytics from 'analytics-web3'; Web3Analytics.init({ appKey: 'eba6...28c' }); Web3Analytics.walletProvider(window.ethereum); ``` ## API ### Web3Analytics.init(options) Web3Analytics must be initialized with `appKey` by invoking init method at the top level of application before using other methods. ```js Web3Analytics.init({ appKey: 'eba6...28c', debug: true }); ```   | Value | Type | Description | | ------------------------| --------| ------------------------------------------------------------| | appKey |`String` | Unique appKey like `eba6...28c` for tracking. Can be obtained by getting [onboarded](#onboarding) in Spock.| | **Optional** | | | | debug |`Boolean`| Defaults to `false`. Enable consoles for all the tracking events.| | dataPoints |`string[]`| By default SDK will track all data points. But you can limit them by passing the desired [datapoints](#datapoints). | | inactivityTimeout |`number` | Defaults to `30`. This field takes time in mins to specify the inactivity duration in which the session will expires.| | optOut |`Boolean` | Defaults to `false`. Opt users out of tracking. | | testENV |`Boolean`| Defaults to `false`. Enable testing version of SDK in which SDK will interact with testing servers.| | testMode |`Boolean`| Defaults to `false`. Enable testMode in which you can test tracking events without logging data onto server. Inordre to avoid store testing data.| ### Web3Analytics.walletProvider(provider) Pass `web3 provider` to track wallet connections for all [Supporting Wallets](#supporting-wallets) and transactions state that are submitted or rejected from DApp. ```js Web3Analytics.walletProvider(window.ethereum); ``` In-case of handling multiple wallets on DApp. Example in `React`. ```js import { useWeb3React } from '@web3-react/core'; const { provider } = useWeb3React(); // in-order to pass updated provider if user changes wallet, account or chain. useEffect(() => { if (provider?.provider) { Web3Analytics.walletProvider(provider.provider); } }, [provider]); ```   | Value | Type | Description | | --------------| --------------| ---------------------------------------------------------------| | provider |`Web3Provider` | EIP-1193 Standard Provider or Web3Provider-compatible Provider.| ### Web3Analytics.trackWalletConnection(walletType,account,chainId) To track other wallets that currently not include in [Supporting Wallets](#supporting-wallets). ```js Web3Analytics.trackWalletConnection('Ledger', '0x...96', 1); ```   | Value | Type | Description | | ----------------| --------| ---------------------------------------------------| | walletType |`String` | Name of wallet | | account |`String` | User ethereum address | | chainId |`number` | User connected chainId | ### Web3Analytics.trackPageView(pathname,search) Track all the pages visited on a DApp. ```js Web3Analytics.trackPageView('/home'); ```   | Value | Type | Description | | ----------------| --------| ---------------------------------------------------| | pathname |`String` | Path of the page. e.g. '/about', '/dashboard/stats'| | search |`String` | Query string of the pgae. eg: '?id=ab02'| ### Web3Analytics.optOutTracking(expiration) Opt user out from tracking. ```js Web3Analytics.optOutTracking(); ```   | Value | Type | Description | | ----------------| --------| ---------------------------------------------------| | expiration |`number` | Default `365`. Duration in days for which user is opt-out.| ### Web3Analytics.optInTracking(expiration) Opt user in tracking. ```js Web3Analytics.optInTracking(); ```   | Value | Type | Description | | ----------------| --------| ---------------------------------------------------| | expiration |`number` | Default `365`. Duration in days for which user is opt-in.| ### Web3Analytics.hasOptedOutTracking() Getter method for the status of user tracking consent. ```js Web3Analytics.hasOptedOutTracking(); ```   | Value | Return Type | Description | | ----------------| --------| ---------------------------------------------------| | - |`Boolean` | Status of user tracking consent.| ### Web3Analytics.widgetOnClick(method) For custom on-click implementation of widget button. ```js Web3Analytics.widgetOnClick(({ campaignId }) => { if (campaignId === YOUR_CAMPAIGN_ID) { //do something } }); ```   | Param | Type | Description | | ----------------| --------| ---------------------------------------------------| | campaignId |`number` | Unique campaign id belongs to the widget.| | redirectUrl |`string / undefined` | Redirect url set on the campaign button click.| ## Supporting wallets - MetaMask - WalletConnect - Coinbase Wallet - Portis - Fortmatic To track wallet not including in the list you can use [trackWalletConnection](#web3analyticstrackwalletconnectionwallettypeaccountchainid) method. ## Datapoints - **_web3_** (**Mandatory**) - Wallet Address, Chain ID, Wallet Type, Wallet Connection, Max Gas Fee, Quoted Gas Fee, Transaction Hash, Transaction Status, Submitted and Rejected Transaction Count and Failed Transactions. - **web2** - Current URL, Operating System, Browser, Referrer, Device, Referring Domain, Screen Width, Screen height, Search Engine, Page Views, External Links and UTM Params. - **_demographics_** - Country, City and Region. - **_engage_** - Campaign Serving, Campaign Clicks, Click Through Rate (CTR), Transaction Through Rate (TTR), Unique Wallets, Dialogs Served, and Dialogs Closed. ## License [UNLICENSED](https://github.com/xorddotcom/spock-sdk/blob/main/LICENSE) ## Demo Example code for `analytics-web3` integration [Spock Analytics Demo](https://github.com/xorddotcom/spock-analytics-demo) ## Documentation You can use these [docs](https://spock-analytics.gitbook.io/spock-analytics-v2/) for knowing more about Spock Analytics. ## Credits Backed by [xord.com](https://xord.com)