\n \n ![\"Ad]()
\n \n \n
\n```\n\nFor entire area click functionality:\n\n```html\n\n ![\"Profile\"]()
\n \n
\n \n \n \n ![\"Ad]()
\n \n \n
\n```\n\n#### Programmatic Loading with Custom UI\n\n```javascript\nconst container = document.getElementById('native-ad-container');\n\nawait adrop.renderAd(container, {\n unit: 'YOUR_NATIVE_UNIT_ID',\n trackMode: 1 // Required for custom UI\n});\n```\n\nFor entire area click functionality:\n\n```javascript\nconst container = document.getElementById('native-ad-container');\n\nawait adrop.renderAd(container, {\n unit: 'YOUR_NATIVE_UNIT_ID',\n trackMode: 1, // Required for custom UI\n isEntireClick: true // Makes entire container clickable\n});\n```\n\n#### Available data-adrop-native Fields\n\nThe SDK supports the following `data-adrop-native` attributes:\n\n**Basic Fields:**\n- `headline`: Ad headline text\n- `body`: Ad description text \n- `callToAction`: Call-to-action button text\n- `asset`: Main ad image URL\n\n**Profile Fields (for advertiser information):**\n- `profile.displayLogo`: Advertiser logo image URL\n- `profile.displayName`: Advertiser name text\n\n**Extra Fields (custom properties):**\n- `extra.{key}`: Custom field from ad data (e.g., `extra.price`, `extra.rating`)\n\n#### Custom UI Implementation Example\n\n```html\n\n ![\"Profile\"]()
\n \n
\n \n \n \n
\n```\n\n#### Click Behavior Control\n\nYou can control how clicks are handled in native ads:\n\n**Individual Element Clicks (default):**\n- Only elements with `data-adrop-native` attributes are clickable\n- Each text and image element handles its own click\n\n**Entire Area Clicks:**\n- Set `data-adrop-entire-click=\"true\"` (declarative) or `isEntireClick: true` (programmatic)\n- The entire ad container becomes clickable\n- Useful for card-style layouts where any part of the ad should be clickable\n\n**Important Notes:**\n- **Custom UI requires `data-adrop-render=\"custom\"` or `trackMode: 1`**\n- **Click behavior: `isEntireClick: true` makes entire area clickable, otherwise only individual elements**\n- The SDK automatically handles click tracking and impression tracking\n- Elements with `data-adrop-native` will be automatically populated with ad content\n- Missing fields will be left empty (no error thrown)\n- Profile clicks redirect to advertiser pages, other clicks go to ad landing pages\n\n### 4. Event Handling\n\nListen to ad lifecycle events:\n\n```javascript\n// Ad received successfully\nadrop.on(Adrop.Events.AD_RECEIVED, (unit, adData) => {\n console.log('Ad received:', unit, adData);\n});\n\n// Ad failed to load\nadrop.on(Adrop.Events.AD_FAILED, (unit) => {\n console.error('Ad failed:', unit);\n});\n\n// No ad available\nadrop.on(Adrop.Events.AD_NO_FILL, (unit) => {\n console.warn('No ad available:', unit);\n});\n\n// No backfill ad available\nadrop.on(Adrop.Events.AD_BACKFILL_NO_FILL, (unit) => {\n console.warn('No backfill ad available:', unit);\n});\n\n// Ad impression\nadrop.on(Adrop.Events.AD_IMPRESSION, (unit, adData) => {\n console.log('Ad impression:', unit, adData);\n});\n\n// Ad clicked\nadrop.on(Adrop.Events.AD_CLICKED, (unit, adData) => {\n console.log('Ad clicked:', unit, adData);\n});\n```\n\n## Advanced Usage\n\n### Update Properties\n\nProperties can be chained and committed together in a single call:\n\n```javascript\n// Set app key\nadrop.appKey = 'YOUR_APP_KEY';\n\n// Chain multiple property updates and commit once\nawait adrop.metrics\n .setUserProperties({\n last_login: new Date().toISOString(),\n age: '25',\n gender: 'M',\n // Custom properties can be added directly\n theme: 'dark',\n language: 'en'\n })\n .setAppProperties({\n version: '1.0.0',\n platform: 'web'\n })\n .commit();\n```\n\n### Context Targeting\n\nUse `contextId` to enable contextual targeting for more relevant ads:\n\n```javascript\nawait adrop.renderAd(container, {\n unit: 'YOUR_UNIT_ID',\n contextId: 'YOUR_CONTEXT_ID' // Context ID from Adrop Console\n});\n```\n\nThe `contextId` should match the ID configured in your Adrop Console under **Targeting Menu > Context Targeting**.\n\n## Theme Support\n\nThe SDK supports light and dark themes for ads. You can set the theme using the `data-adrop-theme` attribute or the `theme` option in `renderAd`.\n\n### Load Backfill Ads\n\nBackfill ads are automatically loaded when direct deal ads are not available.\n\n**Note:** Backfill configuration must be set up in the Adrop Console for this to work.\n\n#### Backfill rendering mode (1.2.3+)\n\n| Mode | Behavior |\n|------|----------|\n| `responsive` (default) | The backfill provider picks a size based on container width. SDK reserves a `min-height` automatically when the container has no explicit height. |\n| `fixed` | Stretches the ad to the container height (`width:100%; height:100%`) — 1.2.1 behavior. Use for slots designed around a fixed height. |\n\n```javascript\n// Global default\nAdrop.observe({ appId: 'YOUR_APP_ID', backfillMode: 'fixed' });\n\n// Per-slot (HTML)\n// \n\n// Per-slot (programmatic)\nawait adrop.renderAd(container, { unit: 'PUBLIC_xxx', backfillMode: 'fixed' });\n```\n\nSee [Backfill rendering mode guide](../docs/web/backfill_mode_guide.md) for details.\n\n### Clear Ads\n\nRemove ads from containers:\n\n```javascript\nconst container = document.getElementById('ad-container');\nadrop.clear(container);\n```\n\n### Reload Ads\n\nIn HTML, you can reload ads by calling:\n\n```javascript\nconst container = document.getElementById('ad-container');\nconst paramsToOverride = {\n unit: 'NEW_UNIT_ID',\n contextId: 'NEW_CONTEXT_ID',\n theme: 'light'\n}\nadrop.renderAd(container, paramsToOverride);\n\n// if you don't want to override previous params, just call without second argument\nadrop.renderAd(container);\n```\n\n### Update User ID\n\n```javascript\nadrop.uid = 'new-user-id';\n```\n\n## Configuration Options\n\n### Initialization Options\n\n```typescript\n{\n uid?: string; // User identifier\n appId?: string; // Application ID\n appKey?: string; // Application key\n debug?: boolean; // Enable debug logging (default: false)\n}\n```\n\n### Ad Request Options\n\n```typescript\n{\n unit: string; // Ad unit ID (required)\n uid?: string; // Override user ID for this request\n contextId?: string; // Context identifier\n keywords?: string[] | string; // Keyword targeting (array or comma-separated string)\n trackMode?: number; // Tracking mode\n}\n```\n\n## Events\n\n- `AD_RECEIVED` - Ad successfully loaded\n- `AD_FAILED` - Ad failed to load\n- `AD_NO_FILL` - No ad available for this request\n- `AD_BACKFILL_NO_FILL` - No backfill ad available\n- `AD_IMPRESSION` - Ad impression recorded\n- `AD_CLICKED` - User clicked on the ad\n\n## TypeScript Support\n\nThe SDK includes TypeScript definitions out of the box:\n\n```typescript\nimport Adrop, { AdropConfig, AdData } from '@adrop/ads-web-sdk';\n\nconst config: AdropConfig = {\n uid: 'user-123',\n debug: true\n};\n\nconst adrop = Adrop.observe(config);\n```\n\n## SPA Support\n\nFor Single Page Applications, clear previous ads when navigating:\n\n```javascript\nfunction navigateToNewPage() {\n // Clear existing ads\n const adElements = document.querySelectorAll('[data-adrop-unit]');\n adElements.forEach(element => adrop.clear(element));\n\n // Load new page content\n loadNewPageContent();\n}\n```\n\n## License\n\nCopyright 2025 Open Rhapsody Co., Ltd.\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n","readmeFilename":"README.md"}\n ![\"Advertiser\"]()
\n \n
\n \n \n \n \n ![\"Ad\"]()
\n \n \n \n
\n\n \n \n
\n \n \n