Offer Wall Widget

A customizable web component for displaying offers and deals on your website

Table of Contents

  1. Getting Started
  2. Installation
  3. Configuration
  4. Customization
  5. CSS Variables
  6. Dark Mode
  7. Filtering Offers
  8. API Reference
  9. Examples
  10. Troubleshooting

Getting Started

Offer Wall Widget is a customizable web component that displays offers in a responsive grid layout and can be fully customized to match your website's design.

Easy Integration

Add a simple HTML tag to your page

Responsive Design

Adapts to different screen sizes

Customizable

Style with CSS variables and ::part

Featured Offers

Highlight your best deals

↑ Back to Contents

Installation

To add the Offer Wall Widget to your website, include the following script tag in your HTML:

<script src="https://cdn.example.com/offer-widget.js"></script>
Note: Replace the URL with the actual URL where your widget script is hosted.
↑ Back to Contents

Configuration

After adding the script to your page, you can place the offer widget anywhere in your HTML using the custom element: 

<offer-widget 
    partnerId="YOUR_PARTNER_ID" 
    partnerName="YOUR_PARTNER_NAME" 
    partnerToken="YOUR_PARTNER_TOKEN">
</offer-widget>

Required Attributes

The following attributes are required for the widget to function properly:

Attribute Description Required
partnerId Your unique partner identifier Required
partnerName Your partner name Required
partnerToken Your authentication token Required
Important: If any of the required attributes are missing, the widget will display an error message.

Example Implementation

Here's a complete example of how to implement the Offer Wall Widget:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>My Offer Page</title>
    <script src="https://cdn.example.com/offer-widget.js"></script>
</head>
<body>
    <h1>Special Offers For You</h1>
    
    <offer-widget 
        partnerId="partner123" 
        partnerName="ExamplePartner" 
        partnerToken="abc123token">
    </offer-widget>
</body>
</html>
↑ Back to Contents

Customization

The widget can be customized using Shadow DOM parts to style specific components.

Shadow DOM Parts

The widget exposes parts that can be styled using the ::part() CSS selector, allowing for detailed customization without affecting the internal structure.

Widget Container Parts

Part Name Description
widget The main widget container
offer-grid The grid container for all offers

Featured Offer Parts

Part Name Description
featured-offer The featured offer container
featured-card The featured offer card
featured-badge The "Featured Deal" badge
featured-image-container Container for the featured offer image
featured-image The featured offer image
featured-logo-container Container for the featured offer logo
featured-logo The featured offer logo
featured-content The featured offer content container
featured-content-inner Inner container for featured offer content
featured-company-name The featured offer company name
featured-name The featured offer name/title
featured-description The featured offer description
featured-action-row Container for the action buttons
featured-claim-button The call-to-action button

Regular Offer Parts

Part Name Description
offer-card The regular offer card
offer-badge The offer badge (e.g., "Limited Time")
offer-image-container Container for the offer image
offer-image The offer image
offer-logo-container Container for the offer logo
offer-logo The offer logo
offer-content The offer content container
offer-name The offer name/title
offer-description The offer description
offer-claim-button The call-to-action button

Styling Example

You can use the ::part selector to customize specific components:

/* Style the main widget container */
offer-widget::part(widget) {
  background-color: #f8f9fa;
  padding: 2rem;
  border-radius: 12px;
}

/* Customize the featured offer */
offer-widget::part(featured-card) {
  border: 2px solid gold;
  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.1);
}

/* Change the CTA button style */
offer-widget::part(featured-claim-button) {
  background-color: #ff4500;
  font-weight: 700;
  text-transform: uppercase;
}

/* Customize the offer cards */
offer-widget::part(offer-card) {
  border-radius: 12px;
  transition: transform 0.3s ease;
}

offer-widget::part(offer-card):hover {
  transform: translateY(-10px);
}
↑ Back to Contents

Styling with CSS Variables

The Offer Wall Widget uses CSS variables for easy theming. You can customize the look and feel by overriding these variables.

Available CSS Variables

Variable Description Default Value
--background Background color of the widget 0 0% 100%
--foreground Text color 222.2 84% 4.9%
--card Card background color 0 0% 100%
--primary Primary color (buttons, accents) 221.2 83.2% 53.3%
--primary-foreground Text color on primary elements 210 40% 98%
--muted-foreground Muted text color 215.4 16.3% 46.9%
--border Border color 214.3 31.8% 91.4%
--radius Border radius for elements 0.5rem
--font-family Font family for the widget System UI fonts

Applying CSS Variables

You can apply CSS variables by targeting the offer-widget element directly:

offer-widget {
  --primary: 220 90% 56%;
  --primary-foreground: 0 0% 100%;
  --card: 0 0% 98%;
  --radius: 0.75rem;
  --font-family: 'Poppins', sans-serif;
}
Tip: CSS variables use the HSL color format with space-separated values. When using in actual CSS properties, convert them with hsl(var(--variable-name)).
↑ Back to Contents

Dark Mode

The Offer Wall Widget supports dark mode by customizing CSS variables.

Enable Dark Mode

Apply dark mode by adding CSS that targets the widget:

/* Manually set dark mode */
offer-widget {
  --background: 222.2 84% 4.9%;
  --foreground: 210 40% 98%;
  --card: 222.2 84% 4.9%;
  --card-foreground: 210 40% 98%;
  --primary: 217.2 91.2% 59.8%;
  --primary-foreground: 210 40% 98%;
  --secondary: 217.2 32.6% 17.5%;
  --muted: 217.2 32.6% 17.5%;
  --muted-foreground: 215 20.2% 65.1%;
  --border: 217.2 32.6% 17.5%;
}

Automatic Dark Mode

Set up automatic dark mode detection using media queries:

@media (prefers-color-scheme: dark) {
  offer-widget {
    --background: 222.2 84% 4.9%;
    --foreground: 210 40% 98%;
    --card: 222.2 84% 4.9%;
    --card-foreground: 210 40% 98%;
    /* Other dark mode variables... */
  }
}
↑ Back to Contents

Filtering Offers

You can filter offers displayed in the widget using a simple expression language. This allows you to show only offers that match specific criteria.

Filter Syntax

The filter syntax supports the following operators:

Operator Description Example
== Equality operator (case-insensitive) category == "Gaming"
AND Logical AND operator category == "Gaming" AND labels == "platform:ios"
OR Logical OR operator category == "Gaming" OR category == "Entertainment"
NOT Logical NOT operator NOT(category == "Gaming")
( ) Grouping parentheses (category == "Gaming" OR category == "Entertainment") AND labels == "platform:ios"

Special Features

Applying Filters

To apply a filter to your widget, add the filter attribute:

<offer-widget 
    partnerId='partner123' 
    partnerName='ExamplePartner' 
    partnerToken='abc123token'
    filter='category == "Gaming" AND labels == "platform:ios"'>
</offer-widget>

Filter Examples

Filter Expression Description
category == "Gaming" Show only Gaming offers
category == "Gaming" OR category == "Entertainment" Show Gaming or Entertainment offers
labels == "platform:ios" Show only iOS platform offers
labels == "genre:*" Show offers with any genre label
NOT(category == "Finance") Show all offers except Finance category
(category == "Gaming" AND labels == "platform:android") OR (category == "Shopping" AND labels == "type:ecommerce") Show Android games or ecommerce shopping offers
Note: Filters are evaluated on the server-side and have limitations for security. Very complex or deeply nested expressions may be rejected.
↑ Back to Contents

API Reference

Element Attributes

Attribute Type Description Required
partnerId String Unique identifier for your partner account Yes
partnerName String Your partner name Yes
partnerToken String Authentication token for API access Yes
filter String Expression to filter offers No

Widget States

The widget has several states that it can display:

↑ Back to Contents

Examples

Basic Implementation

<offer-widget 
    partnerId="partner123" 
    partnerName="ExamplePartner" 
    partnerToken="abc123token">
</offer-widget>

With Custom Styling

<style>
  /* Custom theme with CSS variables */
  offer-widget {
    --primary: 220 75% 60%;
    --radius: 0.75rem;
    --font-family: 'Poppins', sans-serif;
  }
  
  /* Style specific parts */
  offer-widget::part(featured-card) {
    box-shadow: 0 10px 25px rgba(0, 0, 0, 0.1);
    border: none;
  }
  
  offer-widget::part(featured-badge) {
    background-image: linear-gradient(to right, #4f46e5, #8b5cf6);
  }
</style>

<offer-widget 
    partnerId="partner123" 
    partnerName="ExamplePartner" 
    partnerToken="abc123token">
</offer-widget>

With Filtering

<offer-widget 
    partnerId='partner123' 
    partnerName='ExamplePartner' 
    partnerToken='abc123token'
    filter='category == "Gaming" AND labels == "platform:ios"'>
</offer-widget>

With Dark Mode Toggle

<style>
  /* Light mode (default) */
  offer-widget {
    --background: 0 0% 100%;
    --foreground: 222.2 84% 4.9%;
    --card: 0 0% 100%;
    --card-foreground: 222.2 84% 4.9%;
  }
  
  /* Dark mode class */
  offer-widget.dark {
    --background: 222.2 84% 4.9%;
    --foreground: 210 40% 98%;
    --card: 222.2 84% 4.9%;
    --card-foreground: 210 40% 98%;
    --primary: 217.2 91.2% 59.8%;
    --border: 217.2 32.6% 17.5%;
  }
</style>

<button onclick="document.querySelector('offer-widget').classList.toggle('dark')">
  Toggle Dark Mode
</button>

<offer-widget 
    partnerId="partner123" 
    partnerName="ExamplePartner" 
    partnerToken="abc123token">
</offer-widget>
↑ Back to Contents

Troubleshooting

Common issues and their solutions:

Widget displays "Missing required attributes"

Solution: Ensure you've provided all three required attributes: partnerId, partnerName, and partnerToken.

Widget shows "Failed to load offers"

Solution: This usually happens when:

  • Your partner credentials are incorrect
  • There's a network problem
  • The API service is unavailable

Filter expression isn't working

Solution: Check that:

  • Your filter syntax is correct
  • You're using supported operators (==, AND, OR, NOT)
  • Property names match exactly what's in the data
  • String values are properly quoted

Styling not working with ::part selectors

Solution: Make sure you're:

  • Using the correct part name
  • Applying styles after the widget script is loaded
  • Using proper syntax: offer-widget::part(part-name)
Need more help? Contact support at support@example.com for assistance.
↑ Back to Contents