@adshares/decentraland v2.3.1
Adshares plugin for Decentraland SDK. You can use it in your scenes for addition hassle-free earnings.
Easy configuration. Just fill out your payout address (Adshares blockchain or as BEP20 token) and get paid in $ADS for every visitor on your scene. See DCL Example Scene.
Install
npm install @adshares/decentraland -B
Update
npm update @adshares/decentraland
Usage
1. Import dependencies
import * as Ads from '@adshares/decentraland'
2. Create supply agent
const agent = new Ads.SupplyAgent(adserver: string, publisherId: string)
or
const agent = Ads.SupplyAgent.fromWallet(adserver: string, chain: string, wallet: string)
In function fromWallet() first argument is adserver network, second argument is payout network (ads, bsc), and third argument is wallet address in this payout network.
3. Create Placement or Stand
Placements
Placements are the basic objects for displaying creatives. Every placement implements IEntity and has access to IEntity methods.
Usage:
const placement = new Ads.PlainPlacement(name: string, options?: {})
Available options:
{
position?: Vector3, // @decentraland-ecs
rotation?: Quaternion, // @decentraland-ecs
width?: number,
ratio?: '9:16' | '3:4' | '1:1' | '4:3' | '16:9',
no?: number | null,
types?: string[] | null,
mimes?: string[] | null,
}
UI placements
UI placements are elements of interface for displaying creatives, when player is on scene. Keep in might that UI placement doesn't need to be added to Decentraland engine. UI placement can be closed after 5 seconds from displaying.
Usage:
const placement = new Ads.UIPlacement(name: string, position: 'top' | 'bottom' | 'left' | 'right' | 'center')
Stands
Stands combine several placements into one object. Every stand implements IEntity and has access to IEntity methods.
The simplest stand is the PlainStand, which repeats the PlainPlacement and adds a frame and a background that covers the gaps between the layers. You can define own Material for frame.
const plain = new Ads.PlainStand(name: string, options?: {})
Available options:
{
position?: Vector3, // @decentraland-ecs
rotation?: Quaternion, // @decentraland-ecs
width?: number,
ratio?: '9:16' | '3:4' | '1:1' | '4:3' | '16:9',
no?: number | null,
types?: string[] | null,
mimes?: string[] | null,
frameMaterial?: Material,
}
Available stands:
Class | Description | Ratios | Models |
---|---|---|---|
Totem | A simple advertising totem | 9:16 | ads_totem_9_16.glb |
Citylight | Rectangular 4-sided advertising totem with the ability to rotate | 9:16 | ads_citylight_9_16.glb |
Billboard | Advertising billboard with multiple ratios | 9:16 16:9 3:4 4:3 1:1 | ads_billboard_9_16.glb ads_billboard_16_9.glb ads_billboard_3_4.glb ads_billboard_4_3.glb ads_billboard_1_1.glb |
You must copy the models to the root scene folder before using the stands. It's a good practice to copy only the models you use.
mkdir -p models/@adshares && cp -r node_modules/@adshares/decentraland/models/ads_totem_9_16.glb models/@adshares
Usage Totem:
const totem = new Ads.Totem(name: string, options?: {})
Available options:
{
types?: string[] | null,
mimes?: string[] | null,
}
Usage Citylight:
const citylight = new Ads.Citylight(name: string, options?: {})
Available options:
{
types?: string[] | null,
mimes?: string[] | null,
rotation?: boolean, // default true
}
Usage Billboard:
const billboard = new Ads.Billboard(name: string, options?: {})
Available options:
{
types?: string[] | null,
mimes?: string[] | null,
ratio?: '9:16' | '3:4' | '1:1' | '4:3' | '16:9', // default 1:1
}
4. Add placements into Decentraland engine
engine.addEntity(placement)
// or
engine.addEntity(totem)
or
placement.setParent(myEntity)
// or
totem.setParent(myEntity)
5. Add placement into agent and spawn banner
agent.addPlacement(placement: IPlacement | IStand).spawn()
Example to add placements
import * as Ads from '@adshares/decentraland'
const agent = Ads.SupplyAgent.fromWallet('https://app.web3ads.net', 'ads', '0001-00000000-9B6F')
const placement1 = new Ads.PlainPlacement('unit1', {
position: new Vector3(8, 2, 8),
rotation: new Quaternion(0, 0, 0, 1),
width: 5,
ratio: '16:9',
})
engine.addEntity(placement1)
const placement2 = new Ads.PlainPlacement('unit2', {
position: new Vector3(11, 2, 6),
rotation: new Quaternion(0, 1, 0, 1),
width: 3,
ratio: '3:4',
})
engine.addEntity(placement2)
agent.addPlacement(placement1, placement2, totem).spawn()
Example to add advertising stands
import * as Ads from '@adshares/decentraland'
const agent = Ads.SupplyAgent.fromWallet('https://app.web3ads.net', 'ads', '0001-00000000-9B6F')
const totem = new Ads.Totem('totem')
totem.addComponent(new Transform({
position: new Vector3(3,0,8),
}))
engine.addEntity(totem)
const billboard = new Ads.Billboard('billboard_16_9', { ratio: '16:9' })
billboard.addComponent(new Transform({
position: new Vector3(11,0,8),
}))
engine.addEntity(billboard)
agent.addPlacement(totem, billboard).spawn()
Example to add UI placement
import * as Ads from '@adshares/decentraland'
const agent = Ads.SupplyAgent.fromWallet('https://app.web3ads.net', 'ads', '0001-00000000-9B6F')
const uiPlacementRight = new UIPlacement('UI-right', 'right')
const uiPlacementLeft = new UIPlacement('UI-left', 'left')
const uiPlacementCenter = new UIPlacement('UI-center', 'center')
agent.addPlacement(uiPlacementRight, uiPlacementLeft, uiPlacementCenter).spawn()
Contributing
Please follow our Contributing Guidelines
Versioning
We use SemVer for versioning. For the versions available, see the tags on this repository.
Authors
- Mykola Zhura - programmer
- Maciej Pilarczyk - programmer
- Contributor - programmer
See also the list of contributors who participated in this project.
License
This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.