attrace-backend-plugin v0.1.18

Attrace backend plugin for nodejs

The backend client for interfacing with the Attrace network, it uses the universal client under the hood.

Important: if you are building a webapp, please use the lightweight attrace-client npm package. More info: https://www.npmjs.com/package/attrace-client

Usage

1. Install plugin:

   npm install attrace-backend-plugin --save

2. DB Migration Migrate your database by creating table: transactions and agreementconfigs. You could create new or using existing db for this. This is example scripts in SQLite3

   ```sql
   -- Create table transactions
   CREATE TABLE IF NOT EXISTS transactions (
   	txHash TEXT, 
   	base32TxBlob BLOB
   )
   
   -- Create table agreement configs
   CREATE TABLE IF NOT EXISTS agreementconfigs (
   	agreement TEXT, 
   	data BLOB
   )
   
   -- Create index on agreementconfigs.agreements
   CREATE INDEX IF NOT EXISTS idx_agrcf_agr ON agreementconfigs (agreement)
   ```

3. Implement storage interface You have to implement the followings functions

   ```javascript
   async function addTransaction(txHash, txBlob){
   //   + txHash: transaction hash as base32 encoded string
   //   + txBlob: marshaled transaction blob as base32 encoded string
   }
   
   async function addAgreementConfig(agrAddr, blob) {
   //   params: 
   //		+ agrAddr: agreement address of config
   // 		+ blob	 : json encoded agreement configs
   }
   
   async function agreementConfigExisted(agrAddr) {
   //  params:
   //		+ agrAddr: agreement address
   //  return: 
   //  	+ null or undefined if agreement configs not existed in db. 
   // 		+ true if agreement config already existed 
   
   }
   
   async function loadAgreementConfigs() {
   //   + return: array of json encoded agreement configs 
   }
   
   async loadAgreementConfig(agrAddr) {
   //   + params: agrAddr - Agreement address
   //   + return: raw json of agreement config if existed
   }
   ```
   
   You can take a look at [example implementation](https://gitlab.com/attrace/backend-plugin-nodejs-example/-/tree/master/db) using SQLite.

4. Initialize the module

   const storagePlugIn = {
   	addTransaction: addTransaction,
   	agreementConfigExisted: agreementConfigExisted,
   	addAgreementConfig: addAgreementConfig,
   	loadAgreementConfigs: loadAgreementConfigs,
   	loadAgreementConfig: loadAgreementConfig,
   }
   
   Attrace.initialize({
   	network: 'betanet',
   
   	// The base URL where your backend is running, the module needs this to generate the right tag library.
   	backendURL: 'https://yourbackend.url.com',
   
   	// Operational key use to sign transaction.
   	b32PrivateKey: 'IFARTTERXTIA....',  
   
   	// Address of publisher/advertiser owning the campaign
   	delegateOf: 'AA2PE3CZUT22OD6UQ...'
   }, { 
   	logger: console,
   	storage: storagePlugIn
   })

5. Extend your http server with the handlers

   • Express

     	```javascript
     		const app = express()
     
     		// Add the Attrace handlers for 
     		//  /attrace/libs/mtag.js
     		//  /attrace/v1/action
     		//  /attrace/v1/agreementconfigs
     		//  /attrace/v1/plugin-status
     		Attrace.express.install(app)
     
     		app.get('/', function (req, res) {
     			res.send('Hello World')
     		})
     
     		app.listen(3000)
     	```

6. Ready

   • Your service is ready to integrated with Attrace system. The agreement config will be automatically loaded after agreement is confirmed.

   • Your service should now redirect users to the target url and publish transactions Eg: curl -vvvv 'http://localhost:3000/attrace/v1/action?Agreement=ARJUFUYN4G625YLWWS6BDHXVWNKKQ6PMJWL6C35EE5SHDKY5VWB7OPE4'

   • Find the jstag to include in websites where conversion tracking should be done: Eg: curl -vvvv 'http://localhost:3000/attrace/libs/mtag.js'

Example project

You can find an example project using this library here

Module development

Development happens usually using the lonet in the config:

const storagePlugIn = {
		addTransaction: addTransaction,
		agreementConfigExisted: agreementConfigExisted,
		addAgreementConfig: addAgreementConfig,
		loadAgreementConfigs: loadAgreementConfigs,
		loadAgreementConfig: loadAgreementConfig,
	}

Attrace.initialize({
	network: 'lonet',
	discoveryManifestURL: 'https://node.lonet:9178/develop/manifests/lonet',
	backendURL: 'backend-url',
	b32PrivateKey: 'IFARTTERXTIABUWXSIISACK2LC3Q2D7RCC64WOWZV5UXWUCEHLMICU5N2GAM6WQEKDO52REGFGRQV7NS4XT7DQDIBOTVBUPKLEGYTGSN5Y7Q',
	delegateOf: 'AA2PE3CZUT22OD6UQE3F7LU2N7ULLH6R5ZH2GVWNDNIACGD7A62OYAJ3',
}, { 
	logger: console,
	storage: storagePlugIn
})

Debugging

Ping the client process

const res = await Attrace.pingClientProcess()