Instructions on how to create interactive ads by integrating your codes into OpenAD Protocol.
Ad rendering and user interaction will notify publishers and/or advertisers upon request. This feature is suitable for providing traditional gaming incentive scenarios to publisher TMAs, such as extra lives for ad viewing.
Interactive ads will be presented in full screen, ads will be displayed for a certain time, and the number of impressions is calculated by CPM.
OpenAD will notify publishers of ad display events,
onAdResourceLoad, indicates load ad resource from OpenAD platform, false will be returned if there is no resource to be loaded for the publisher slot/zone,
onAdOpening, indicates the interactive ad is opening,
onAdOpened, indicates the interactive ad is opened,
onAdTaskFinished, indicates the interactive ad task is finished, the task is defined by advertiser,
onAdClosing, indicates the interactive ad is closing,
onAdClosed, indicates the interactive ad is closed.
onAdClick, indicates clicked and jumps.
This document provides instructions on how to use OpenAD js SDK to create interactive ads on PC (Desktop Web App), Mobile H5 (Mobile Web App), and TMA (Telegram Mini App).
Step #1. Load SDK
Load the SDK in the body of html, the code is as follows:
The following global vairables will be loaded with 'https://protocol.openad.network/tg/sdk.loader.js'.
openADSdkLoader.hostURL , node api url to serve end user. e.g., https://bf2055756e.api.openad.network .
The script will pick OpenAD node for your end users, and load proper version of OpenAD SDK for you.
Step #2. Init OpenAD resource for interactive ad
The interactive ads shall be init manually.
Please follow the guideline to add the following js code.
1. If your web application is a TMA (Telegram Mini App), please use the following codes.
/* ... */
// Create an AD object
const TGAD = {
adInfo: {
zoneId: 159, // int, This is an example zoneId, please get your own code parameters
publisherId: 49, // int, This is an example publisherId, please get your own code parameters
},
adParams: {
TG: {
type: 'TMA', // TMA, WEB, WEB3,
isFullscreen: false, // true: If your TMA is in fullscreen mode
},
wallet: { // If you have a web3 wallet components, Optional
type: '', // eth: eth wallet, kaia: line wallet, ton: ton wallet;
provider: null, // here is a provider object after wallet initialization.
components: '', // web3 wallet components name
},
},
};
2. If your web application is a web3 app and has a wallet provider, please use the following codes.
/* ... */
const TGAD = {
adInfo: {
zoneId: 159, // int, This is an example zoneId, please get your own code parameters
publisherId: 49, // int, This is an example publisherId, please get your own code parameters
},
adParams: {
TG: {
type: 'WEB3',
},
wallet: { // TG.type = 'WEB3', wallet is required
type: '', // eth: eth wallet, kaia: line wallet, ton: ton wallet;
provider: null , // this is a demo to use @townsquarelabs/ui-vue, Modal is the wallet provider
components: '', // web3 wallet components name
},
},
userInfo: { // TG.type = 'WEB3', userInfo is required
userId: 'vincent', // user ID, is required
firstName: 'firstName', // firstName or userId, is required
lastName: 'lastName', // lastName or userId, is required
username: 'username', // username or userId, is required
},
};
/* ... */
When wallet pass into SDK, please initialize the user's wallet in advance to ensure that wallet.provider can get the user's wallet address;
When wallet.type = 'eth', you should use codes as below;
/* ... */
// if you are using reown
const Modal = createAppKit({
adapters: [ wagmiAdapter ],
networks: [ mainnet, arbitrum ],
defaultNetwork: mainnet,
projectId,
features: {
analytics: true, // Optional - defaults to your Cloud configuration
email: false,
socials: [ ],
emailShowWallets: false,
allWallets: 'SHOW',
},
});
wallet: {
type: 'eth',
provider: Modal,
components: '@reown',
},
/* ... */
When wallet.type = 'kaia', you should use codes as below;
When wallet.type = 'ton', you should use codes as below;
/* ... */
// if you are using useTonConnectUI
const { tonConnectUI } = useTonConnectUI();
const userFriendlyAddress = useTonAddress();
wallet: {
type: 'ton',
provider: {
...tonConnectUI.account,
userFriendlyAddress,
},
components: '@tonconnect/ui',
}
/* ... */
3. If your web application is a web3 app and wallet was created by backend, please use the following codes.
/* ... */
const TGAD = {
adInfo: {
zoneId: 159, // int, This is an example zoneId, please get your own code parameters
publisherId: 49, // int, This is an example publisherId, please get your own code parameters
},
adParams: {
line: {
type: 'WEB3',
},
wallet: { // TG.type = 'WEB3', wallet is required
type: 'api', //
method: 'get', // GET / POST, method is required
chainType: 'eth', // eth, ton, kaia; chainType is required
api: 'https://host/...api', // here is the required API. We will call this API to get user's wallet.
},
},
userInfo: { // TG.type = 'WEB3', userInfo is required
userId: 'vincent', // user ID, is required
firstName: 'firstName', // firstName or userId, is required
lastName: 'lastName', // lastName or userId, is required
username: 'username', // username or userId, is required
},
};
for example, if method = 'GET', request url = 'https://host/...api?userId=xxx';
response = {
data: '', // data must be a valid string, or SDK will reject.
}
/* ... */
4. If your web application is a web app, please use the following codes.
/* ... */
const TGAD = {
adInfo: {
zoneId: 159, // int, This is an example zoneId, please get your own code parameters
publisherId: 49, // int, This is an example publisherId, please get your own code parameters
},
adParams: {
TG: {
type: 'WEB',
},
web: { // TG.type = 'WEB', web is required
token: 'data', // response object key, how to get token value.
valid: 171, // token's length. either string or numeric type is acceptable.
method: 'get', // GET / POST, method is required.
api: 'https://host/...api', // here is the required API. We will call this API to get user's wallet.
},
},
userInfo: { // TG.type = 'WEB', userInfo is required
userId: 'vincent', // user ID, is required
firstName: 'firstName', // firstName or userId, is required
lastName: 'lastName', // lastName or userId, is required
username: 'username', // username or userId, is required
},
};
for example, if method = 'GET', request url = 'https://host/...api?userId=xxx';
response = {
data: '', // data must be a valid string, or SDK will reject.
}
/* ... */
init/load OpenAD resource manually
/* ... */
window.OpenADTGJsSDK.interactive.init({ ...TGAD }).then(res => {
if(res.code === 0){
// you can callback 'getRender' function, user can load an interactive ad;
}else{
// you can't callback 'getRender' function, user can't load an interactive ad;
}
})
/* ... */
Step #3. Get Ad And Render
// Create a callback object
// view AD steps is [1,2,3,5,6,7], click steps is [1,2,3,6,7,5,4]
const callbackFunc = {
// Indicates load ad resource from OpenAD platform, false will be returned if there is no resource to be loaded for the publisher slot/zone
onAdResourceLoad: (e) => {
// 'step1', e = true / false
},
// Indicates the interactive ad is opening
onAdOpening: (e) => {
// 'step2', e = true / false
},
// Indicates the interactive ad is opened,
onAdOpened: (e) => {
// 'step3', e = true / false
},
// indicates the interactive ad task is finished, the task is defined by publisher
onAdTaskFinished: (e) => {
// 'step5', e = true / false
},
// Indicates the interactive ad is closing
onAdClosing: (e) => {
// 'step6', e = true / false
},
// Indicates the interactive ad is closed
onAdClosed: (e) => {
// 'step7', e = view / click / close
// view: viewed Ad completed, not clicked, not manually closed ads; client side needs to issue rewards level 1.
// click: click Ad completed, include viewed Ad, not manually closed ads; client side needs to issue rewards level 2.
// close: user manually closed ads. client side can not get any rewards.
// If you want to perform different steps based on different shutdown states, please write the code here.
},
// Indicates clicked and jumps
onAdClick: (e) => {
// 'step4', e = true / false
},
};
// Call SDK method to get advertising and render data
window.OpenADTGJsSDK.interactive.getRender({ adInfo, cb: callbackFunc });
Notices
After executing the init method, determine whether to continue executing the getRender method based on the status of res.code!
Please pay attention to your page flow design, there may be res.code !== 0. In the case of res.code === 0, please execute the getRender method as soon as possible. The data is time-sensitive. After the timeout, the ad delivery will be invalid.
There are 7 callback methods for calling the getRender method, which can be called on demand!
The client must re-execute the init method every time to determine whether the AD can be loaded. Otherwise, the data statistics will only take effect once, and multiple repeated impressions cannot be counted!!!
