Complete data structure reference and best practices for displaying AIARCO ads in your UI.

​
Offer Data Structure

Every offer returned by the API follows this schema. Only id, title, content, cta, clickUrl, source, and ad_type are guaranteed. All other fields are present only when the advertiser provides them.
FieldTypeDescription
idstringUnique impression UUID. Used for tracking.
titlestringAd headline text.
contentstringAd description / body text.
ctastringCall-to-action label (e.g. “Shop Now”, “Learn More”).
clickUrlstringClick-tracking URL. Redirects to the advertiser’s landing page. Always use this for links.
sourcestringAlways "aiarco".
ad_typestringAd format: sponsored_result, native_ad, banner, interstitial, video_pre_roll, text_link.
subtitlestring?Secondary headline text.
imageUrlstring?Hero image URL.
brand.namestring?Advertiser brand name.
brand.descriptionstring?Brand description.
brand.urlstring?Brand website URL.
brand.iconUrlstring?Brand icon/logo URL.
product.productIdstring?Product identifier.
product.titlestring?Product name.
product.categorystring?Product category path.
product.availabilitystring?Availability status.
price.amountnumber?Current price.
price.currencystring?Currency code (e.g. “USD”).
price.originalPricenumber?Original price before discount.
price.discountnumber?Discount percentage.
rating.valuenumber?Rating value.
rating.scalenumber?Rating scale (default 5).
rating.countnumber?Number of ratings.
metadata.contextstring?Additional context from the advertiser.

​
Rendering Example

​
React / Next.js

function OfferCard({ offer }) {
  return (
    <div className="border rounded-lg p-4 bg-white">
      {/* Sponsored badge */}
      <span className="text-xs text-gray-500 bg-gray-100 px-2 py-0.5 rounded">
        Sponsored
      </span>

      {/* Brand */}
      {offer.brand && (
        <div className="flex items-center gap-2 mt-2">
          {offer.brand.iconUrl && (
            <img src={offer.brand.iconUrl} alt="" className="w-5 h-5 rounded" />
          )}
          <span className="text-xs text-gray-500">{offer.brand.name}</span>
        </div>
      )}

      {/* Hero image */}
      {offer.imageUrl && (
        <img src={offer.imageUrl} alt="" className="w-full rounded mt-2" />
      )}

      {/* Title + content */}
      <h3 className="font-semibold mt-2">{offer.title}</h3>
      {offer.subtitle && (
        <p className="text-sm text-gray-600">{offer.subtitle}</p>
      )}
      <p className="text-sm text-gray-700 mt-1">{offer.content}</p>

      {/* Price */}
      {offer.price && (
        <div className="mt-2">
          <span className="font-bold">
            {offer.price.amount} {offer.price.currency}
          </span>
          {offer.price.originalPrice && (
            <span className="line-through text-gray-400 text-sm ml-2">
              {offer.price.originalPrice}
            </span>
          )}
          {offer.price.discount && (
            <span className="text-red-600 text-sm ml-1">
              {offer.price.discount}% off
            </span>
          )}
        </div>
      )}

      {/* Rating */}
      {offer.rating && (
        <div className="text-sm mt-1">
          {"★".repeat(Math.round(offer.rating.value))}
          {"☆".repeat(
            (offer.rating.scale || 5) - Math.round(offer.rating.value),
          )}
          {offer.rating.count && (
            <span className="text-gray-500 ml-1">({offer.rating.count})</span>
          )}
        </div>
      )}

      {/* CTA */}
      <a
        href={offer.clickUrl}
        target="_blank"
        rel="noopener sponsored"
        className="inline-block bg-blue-600 text-white px-4 py-2 rounded mt-3 text-sm"
      >
        {offer.cta}
      </a>
    </div>
  );
}

​
HTML / Vanilla JS

function renderOffer(offer) {
  return `
    <div class="aiarco-ad" data-aiarco-id="${offer.id}">
      <span class="badge">Sponsored</span>
      <h3>${offer.title}</h3>
      <p>${offer.content}</p>
      ${offer.price ? `<span class="price">${offer.price.amount} ${offer.price.currency || ""}</span>` : ""}
      <a href="${offer.clickUrl}" target="_blank" rel="noopener sponsored">
        ${offer.cta}
      </a>
    </div>
  `;
}

​
Best Practices

  • Always use clickUrl — it includes built-in click tracking. Never construct click URLs manually.
  • Add rel="noopener sponsored" to all ad links for SEO compliance and security.
  • Label ads as “Sponsored” — include a visible badge or label. This is required for regulatory compliance.
  • Handle missing fields gracefully — only id, title, content, cta, and clickUrl are guaranteed. Check for the existence of optional fields before rendering.
  • Track impressions after render — see Tracking for viewability reporting.
  • Set data-aiarco-id on the container element if using the SDK’s IntersectionObserver for automatic impression tracking.