Create Banner Ads

Instructions on how to create banner ads by integrating your codes into OpenAD Protocol.

`Preparations`

Make sure that you complete Create Your Ad Placement before you start the following steps.

`Github Codes And Demo`

https://github.com/openad-protocol/openad-tg-ad-demo

`Easy embedding`

Step #1. Load SDK

Load the SDK in the body of html, the code is as follows:

<head>
  <!--Your codes above-->
  <script
      name="OpenADTGJsSDK"
      version="4.0"
      type="text/javascript"
      src="https://protocol.openad.network/tg/sdk.loader.js">
  </script>
</head>

We recommend to add your application version number or release timestamp after JS to obtain the latest JS SDK for your application. E.g.,

https://protocol.openad.network/tg/sdk.loader.js?t=your-app-release-timestamp

https://protocol.openad.network/tg/sdk.loader.js?v=your-app-version

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. Add DOM placeholder for Ad banner

<body>
  <!-- code before banner -->
  <div class="OpenADJsSDKBanner #your_style_class" 
       publisherld="49"
       zoneld="158">
  </div>
  <!-- code after banner -->
</body>

zoneld="158", 158 is a demo zoneld, please use your own "zoneId"

publisherld="49", 49 is a demo publisherld, please use your own "publisherld"

feel free to define your own banner style

OpenAD SDK will get ad banner for your end users and has it rendered in the DOM placeholder.

In traditional web applications, you can see OpenAD banner been rendered.

!!! OpenAD only support ONE DOM placeholder in one web page.

Enjoy the OpenAD ecosystem !!!

Step #3. Init OpenAD Resource

In most SPA (single page application) web frameworks, DOM objects are rendered dynamically. Thus, the ad banner shall be init manually, the init js call will render ad banners to predefined DOM placeholder.

Please follow the guideline to add the following js codes.

1. If your web application is a TMA (Telegram Mini App), please use the following codes.

/* ... */

// Create an AD object
const TGAD = {
  adInfo: {
    zoneId: 158, // 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
    },
    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: 158, // 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;

/* ... */
import DappPortalSDK from '@linenext/dapp-portal-sdk'
const sdk = await DappPortalSDK.init({ clientId: '<CLIENT_ID>' });
const provider = sdk.getWalletProvider();

wallet: {
  type: 'kaia',
  provider: provider,
  components: 'dapp-portal-sdk'
}
/* ... */

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: 158, // 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: 158, // 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.banner.init({ ...TGAD });
/* ... */

`Explicit Call Functions`

1. Load SDK

.......

2. Get Ad Info

// // Ad resource object structure, banner
// resource = {
//    type         : 'banner',
//    resource_url : string, // resource url
//    width        : int,    // resource width
//    height       : int,    // resource height
//    resource_id  : int     // resource ID
//};

// Create an AD object
// for detail, please view 'Step #3'.

// Call SDK method to get advertising data
const res = await window.OpenADTGJsSDK.banner.get({ ...TGAD });
if ( res.code === 0 ) {
   const resource = res.data;
   // After getting the data, you can render it on the page
   // you can add multiple ad banners
}else{
   // We recommend not throwing an error
}

3. Log User View

When the page loads the ad resources and users can see the ads, please execute the following SDK method.

const res = await window.OpenADTGJsSDK.banner.log(adInfo);
if ( res.code === 0 ) {
   // Callback log info successful
}else{
   // We recommend not throwing an error
}

4. Log User Click

When users click on the ad, please execute the following SDK method:

window.OpenADTGJsSDK.banner.click(adInfo);

SDK will open a new app by the above function;

No Callback, if you want to do sth, you should use yourself functions or methods;

PreviousHow to Integrate OpenAD?NextCreate Interactive Ads

Last updated 7 months ago