Extended Advertisement contract
- Contract architecture
- Features
- How to test
Extended Advertisement contract is responsible for maintaining campaigns for user acquisition using an extension of the AppCoins protocol. As with Advertisement contract, Extended Advertisement contract is upgradable. Thus, Extended Advertisement contract retains the contract's logic and Extended Advertisement Storage contract handles and stores every information required by the Extended Advertisement contract.
Extended Advertisement contract remains responsible for managing all AppCoins deposited by developers with intent of running extended user acquisition campaigns. As of this fact, Extended Advertisement Finance contract is responsible for storing AppCoins for that purpose.
As Advertisement Storage and Advertisement Finance contracts, both Extended Advertisement Storage and Extended Advertisement Finance require that only the Extended Advertisement contract is able to make function calls modifying contract's state.
Anyone can create a campaign for user aquisition using the extended version of the AppCoins protocol.
- Call the method
createCampaign. You need Gas and AppCoins to run this command.
To create a campaign for a certain app, a developer first need to allow the Extended Advertisement contract to transfer the budget of the campaign to the Extended Advertisement contract (approve function). After this step, calling the function createCampaign with following arguments:
| Name | Description |
|---|---|
| packageName | Package name of the app promoted in the campaign |
| countries | List of countries on which the campaign can be converted |
| vercodes | List of version codes of the app allowing campaign conversion |
| price | Amount of AppCoins the developer will be paying per installation |
| budget | Total budget of AppCoins the developer will spend on the campaign |
| startDate | Date for the beginning of the campaign |
| endDate | Date for the termination of the campaign |
| endPoint | URL of the web service responsible for signing a PoA |
Compared with Advertisement contract, an additional argument is required, as extended user acquisition campaigns offload PoA validation to offchain services (see User Acquisition Extended). Anyone is able to create and cancel a campaign as well as to get campaign details, however the submission of proofs of attention is restricted to whitelisted addresses. Countries are encoded as explained in Advertisement contract wiki page.
See Advertisement contract wiki page.
In order to get campaign details the same methods described in Advertisement contract wiki page are available. Furthermore, as extended user acquisition campaigns store an additional argument to provide the Web service endpoint for validating and submitting PoAs, a new get function is provided:
getEndPointOfCampaign
As Extended Advertisement contract stores PoA rewards until the address registering them decides to withdraw the rewards, an additional function to provided de current balance of rewards a certain address can withdraw is provided by getBalance function. This function can only be called by white listed addresses.
The registration of proofs of attention to the blockchian is done through a whitelisted party, responsible for validating a proof of attention, as presented in User Aquisition Extended protocol.
Once a proof of attention is computed, the proof is sent to a signing service defined during campaign creation. The signing service is a trusted third-party registered in the Extended Advertisement contract. The signing service is responsible for validating and siging the submitted PoA. Once a defined amount of proofs for a certain campaign are received, the service calls bulkRegisterPoA function of the Extended Advertisement Contract.
The bulkRegisterPoA can only be called by white listed addresses and expects as an argument, the campaign id, the root hash of every PoA registered that campaign, the root hash signed by the signing service and the number of new hashes added since the last submission.
Finally, the Extended Advertisement Contract updates the balance of the signing service on the Extended Finance Contract and emits a BulkPoARegistered event with the information received as argument from bulkRegisterPoA function call.
Only white listed addresses are able to withdraw previously registered rewards. As presented in User aquisition extended, only white listed addresses are able to register a PoA. Furthermore, using Extended Advertisement contract, each time a PoA is registered, the corresponding Appcoins are internally transfered to the address registering them.
At some point the entity registering PoAs can withdraw it's funds by calling withdraw function. Once this function is called, all rewards balance retain for the address calling the function is transfered to the address and the balance within Extended Advertisement contract is reset to 0.
In order to sign the message you are going to need the user private key, and the message.
Example on how to sign in Javascript:
var userPrivateKey = "0x2bdd21761a483f71054e14f5b827213567971c676928d9a1808cbfa4b7501202"; var message = "message"; var object = await web3.eth.accounts.sign(msg, privateKey0);
the object will have this configuration:
web3.eth.accounts.sign(message, userPrivateKey);
> {
message: 'Some data',
messageHash: '0x1da44b586eb0729ff70a73c326926f6ed5a25f5b056e7f47fbc6e58d86871655',
v: '0x1c',
r: '0xb91467e570a6466aa9e9876cbcd013baba02900b8979d43fe208a4a4f339f5fd',
s: '0x6007e74cd82e037b800186422fc2da167c747ef045e5d18a5f5d4300f8e1a029',
signature: '0xb91467e570a6466aa9e9876cbcd013baba02900b8979d43fe208a4a4f339f5fd6007e74cd82e037b800186422fc2da167c747ef045e5d18a5f5d4300f8e1a0291c'
}
from here you will need the messageHash and the signature, then call the method bulkRegisterPoA:
addInstance.bulkRegisterPoA.sendTransaction(bid, object.messageHash, object.signature, 1, {from: accounts[1]})
to test the signature in the ropsten, use the deployed contract https://ropsten.etherscan.io/address/0xf1cfca1355c8ae9a98f27de6880ae9c36c676b9d