Semantic Objects

Introduction

Semantic Objects (allong with their Attribute) allow you to track data that can add extra functionality to Fanplayr 360. For example you may track an event for product views with the Attribute Key $product which may then be shown in the list of Top 10 Products by View in Insights / Products.

Semantic Attributes can be used with any tracking call. Semantic Events may support specific Semantic Attributes, for example when using $order with the Order Completed event, Fanplayr 360 will use the details to display total Revenue in Insights.

These attributes will be pre-populated in the Data Dictionary.

Following is a list that defines the structure for these Semantic Objects, along with the attribute key and any related Semantic Attributes.

Product

Represents a product in an e-commerce store.

Interface

interface Product {
  id?: string
  sku?: string
  name?: string
  categories?: string[]
  price?: number
  quantity?: number
  url?: string
  imageUrl?: string
  currency?: string
  variant?: string
  color?: string
  size?: string
  brand?: string
}

JavaScript API

fp360.track('AN_EVENT', {
  $product: {
    id: "23489023",
    sku: "23489023",
    name: "Red Shoes",
    categories: [
      "Shoes & Accessories > Shoes",
      "Shoes & Accessories > Shoes > Women Shoes"
    ],
    price: 49.95,
    quantity: 1,
    url: "https://example.com/products/23489023",
    imageUrl: "https://example.com/products/23489023.jpg",
    currency: "USD",
    variant: "Striped",
    color: "Red",
    size: "US 8",
    brand: "Nike"
  }
})

Custom API

{
  ...<EVENT_MESSAGE_PROPERTIES>,
  "event": "AN_EVENT",
  "properties": {
    $product: {
      "id": "23489023",
      "sku": "23489023",
      "name": "Red Shoes",
      "categories": [
        "Shoes & Accessories > Shoes",
        "Shoes & Accessories > Shoes > Women Shoes"
      ],
      "price": 49.95,
      "quantity": 1,
      "url": "https://example.com/products/23489023",
      "imageUrl": "https://example.com/products/23489023.jpg",
      "currency": "USD",
      "variant": "Striped",
      "color": "Red",
      "size": "US 8",
      "brand": "Nike"
    }
  }
}

Products

Represents a group of Products.

• Attribute Key - $products

• products - Product

Interface

type Products = Array<Product>

JavaScript API

fp360.track('AN_EVENT', {
  $products: [
    {
      id: "23489023",
      sku: "23489023",
      name: "Red Shoes",
      categories: [
        "Shoes & Accessories > Shoes",
        "Shoes & Accessories > Shoes > Women Shoes"
      ],
      price: 49.95,
      quantity: 1,
      url: "https://example.com/products/23489023",
      imageUrl: "https://example.com/products/23489023.jpg",
      currency: "USD",
      variant: "Striped",
      color: "Red",
      size: "US 8",
      brand: "Nike"
    },
    {
      id: "123",
      name: "Another Product"
    }
  ]
})

Example JSON

[
  {
    "id": "23489023",
    "sku": "23489023",
    "name": "Red Shoes",
    "categories": [
      "Shoes & Accessories > Shoes",
      "Shoes & Accessories > Shoes > Women Shoes"
    ],
    "price": 49.95,
    "quantity": 1,
    "url": "https://example.com/products/23489023",
    "imageUrl": "https://example.com/products/23489023.jpg",
    "currency": "USD",
    "variant": "Striped",
    "color": "Red",
    "size": "US 8",
    "brand": "Nike"
  },
  {
    "id": "123",
    "name": "Another Product"
  }
]

Cart

Represents a shopping cart in a store.

• Attribute Key - $cart

• products - Product
• location - Location

Interface

interface Cart {
  id?: string
  revenue?: number
  revenueAccountCurrency?: number
  currency?: string
  discount?: number
  discountAccountCurrency?: number
  discountCode?: string
  tax?: number
  taxAccountCurrency?: number
  shipping?: number
  shippingAccountCurrency?: number
  products?: Product[]
  location?: Location
}

JavaScript API

fp360.track('AN_EVENT', {
  $cart: {
    id: "5f26d70f-df43-4f7c-b8b9-fe0b2659575f",
    revenue: 73.40,
    discount: 10.00,
    discountCode: "10OFF",
    tax: 5.00,
    shipping: 7.00,
    currency: "USD",
    products: [
      {
        id: "23489023",
        sku: "23489023",
        name: "Red Shoes",
        categories: [
          "Shoes & Accessories > Shoes",
          "Shoes & Accessories > Shoes > Women Shoes"
        ],
        price: 49.95,
        quantity: 1,
        url: "https://example.com/products/23489023",
        imageUrl: "https://example.com/products/23489023.jpg",
        currency: "USD",
        variant: "Striped",
        color: "Red",
        size: "US 8",
        brand: "Nike"
      }
    ],
    location: {
      country: "United States",
      countryCode: "US",
      region: "California",
      city: "Palo Alto",
      postalCode: "94301",
      street: "725 Alma Street",
      text: "725 Alma Street, Palo Alto, CA 94301",
      latitude: 37.44178713736534,
      longitude: -122.16064940120228
    }
  }
}

Example JSON

{
  "id": "5f26d70f-df43-4f7c-b8b9-fe0b2659575f",
  "revenue": 73.40,
  "discount": 10.00,
  "discountCode": "10OFF",
  "tax": 5.00,
  "shipping": 7.00,
  "currency": "USD",
  "products": [
    {
      "id": "23489023",
      "sku": "23489023",
      "name": "Red Shoes",
      "categories": [
        "Shoes & Accessories > Shoes",
        "Shoes & Accessories > Shoes > Women Shoes"
      ],
      "price": 49.95,
      "quantity": 1,
      "url": "https://example.com/products/23489023",
      "imageUrl": "https://example.com/products/23489023.jpg",
      "currency": "USD",
      "variant": "Striped",
      "color": "Red",
      "size": "US 8",
      "brand": "Nike"
    }
  ],
  "location": {
    "country": "United States",
    "countryCode": "US",
    "region": "California",
    "city": "Palo Alto",
    "postalCode": "94301",
    "street": "725 Alma Street",
    "text": "725 Alma Street, Palo Alto, CA 94301",
    "latitude": 37.44178713736534,
    "longitude": -122.16064940120228
  }
}

Order

Represents a transaction in a store, such as a completed or returned order.

• Attribute Key - $order

• products - Product
• location - Location
• billingLocation - Location
• shippingLocation - Location

Interface

interface Order {
  orderNumber?: string
  revenue?: number
  revenueAccountCurrency?: number
  cartId?: string
  discount?: number
  discountAccountCurrency?: number
  discountCode?: string
  tax?: number
  taxAccountCurrency?: number
  shipping?: number
  shippingAccountCurrency?: number
  products?: Product[]
  location?: Location
  billingLocation?: Location
  shippingLocation?: Location
  returnReference?: string
  returnReason?: string
  cashier?: string
  salesperson?: string
}

JavaScript API

fp360.track('AN_EVENT', {
  orderNumber: "34859456045",
  returnReference: "9764383",
  returnReason: "Change of mind",
  revenue: 73.40,
  tax: 5.00,
  currency: "USD",
  cashier: "John",
  products: [
    {
      id: "23489023",
      sku: "23489023",
      name: "Red Shoes",
      categories: [
        "Shoes & Accessories > Shoes",
        "Shoes & Accessories > Shoes > Women Shoes"
      ],
      price: 49.95,
      quantity: 1,
      url: "https://example.com/products/23489023",
      imageUrl: "https://example.com/products/23489023.jpg",
      currency: "USD",
      variant: "Striped",
      color: "Red",
      size: "US 8",
      brand: "Nike"
    }
  ],
  location: {
    id: "243850934",
    name: "Fanplayr HQ",
    country: "United States",
    countryCode: "US",
    region: "California",
    city: "Palo Alto",
    postalCode: "94301",
    street: "725 Alma Street",
    text: "725 Alma Street, Palo Alto, CA 94301",
    latitude: 37.44178713736534,
    longitude: -122.16064940120228
  }
})

Example JSON

{
  "orderNumber": "34859456045",
  "returnReference": "9764383",
  "returnReason": "Change of mind",
  "revenue": 73.40,
  "tax": 5.00,
  "currency": "USD",
  "cashier": "John",
  "products": [
    {
      "id": "23489023",
      "sku": "23489023",
      "name": "Red Shoes",
      "categories": [
        "Shoes & Accessories > Shoes",
        "Shoes & Accessories > Shoes > Women Shoes"
      ],
      "price": 49.95,
      "quantity": 1,
      "url": "https://example.com/products/23489023",
      "imageUrl": "https://example.com/products/23489023.jpg",
      "currency": "USD",
      "variant": "Striped",
      "color": "Red",
      "size": "US 8",
      "brand": "Nike"
    }
  ],
  "location": {
    "id": "243850934",
    "name": "Fanplayr HQ",
    "country": "United States",
    "countryCode": "US",
    "region": "California",
    "city": "Palo Alto",
    "postalCode": "94301",
    "street": "725 Alma Street",
    "text": "725 Alma Street, Palo Alto, CA 94301",
    "latitude": 37.44178713736534,
    "longitude": -122.16064940120228
  }
}

Message

Represents a message that has been sent to a user through a medium such as postal mail, email, SMS, web push notification etc.

• Attribute Key - $message

Interface

interface Message {
  type?: string
  recipient?: string
  id?: string
  subject?: string
  campaign?: string
  browser?: string
  os?: string
  device?: string
}

JavaScript API

fp360.track('AN_EVENT', {
  $message: {
    id: "23384534543",
    type: "email",
    recipient: "[e-mail]",
    subject: "You left something in cart!",
    campaign: "Abandoned Cart"
  }
})

Example JSON

{
"id": "23384534543",
"type": "email",
"recipient": "[e-mail]",
"subject": "You left something in cart!",
"campaign": "Abandoned Cart"
}

• id - a unique identifier for this message that remains the same between message events such as Message Sent or Message Delivered.
• type - the type of message such as "email", "sms", "notification", "line" or "whatsapp".

• recipient - the email address, phone number, or other identifier that is used to send the message.

• subject - used for the subject of an email or similar.

• campaign - the name of the campaign used to send the message. Examples may be "Abandoned Cart" and "Summer 2022 Sale".

Location

Represents a physical location tied to an event.

• Attribute Key - $location or $billingLocation or $shippingLocation

Different attribute keys let Fanplayr 360 know a location is used for different purposes.

Interface

interface Location {
  id?: string
  name?: string
  country?: string
  countryCode?: string
  region?: string
  city?: string
  postalCode?: string
  street?: string
  text?: string
  latitude?: number
  longitude?: number
}

JavaScript API

fp360.track('AN_EVENT', {
  $location: {
    id: "243850934",
    name: "Fanplayr HQ",
    country: "United States",
    countryCode: "US",
    region: "California",
    city: "Palo Alto",
    postalCode: "94301",
    street: "725 Alma Street",
    text: "725 Alma Street, Palo Alto, CA 94301",
    latitude: 37.44178713736534,
    longitude: -122.16064940120228
  }
})

Example JSON

{
  "id": "243850934",
  "name": "Fanplayr HQ",
  "country": "United States",
  "countryCode": "US",
  "region": "California",
  "city": "Palo Alto",
  "postalCode": "94301",
  "street": "725 Alma Street",
  "text": "725 Alma Street, Palo Alto, CA 94301",
  "latitude": 37.44178713736534,
  "longitude": -122.16064940120228
}

Search

Represents a search performed on an e-commerce website.

• Attribute Key - $search

Interface

interface Search {
  query?: string
}

JavaScript API

fp360.track('AN_EVENT', {
    query: "red shoes"
})

Example JSON

{
  "query": "red shoes"
}

Recommendation

Represents a recommendation made in an e-commerce store or application.

• Attribute Key - $recommendation

• products - Product

Interface

interface Recommendation {
  id?: string
  products?: Product[]
  model?: string
  productDisplayId?: string
  widgetId?: string
}

JavaScript API

fp360.track('AN_EVENT', {
  id: "7812087d-d7ff-46d7-a790-eb60c4bb679f",
  model: "Others You May Like",
  products: [
    {
      id: "23489023",
      sku: "23489023",
      name: "Red Shoes",
      categories: [
        "Shoes & Accessories > Shoes",
        "Shoes & Accessories > Shoes > Women Shoes"
      ],
      price: 49.95,
      quantity: 1,
      url: "https://example.com/products/23489023",
      imageUrl: "https://example.com/products/23489023.jpg",
      currency: "USD",
      variant: "Striped",
      color: "Red",
      size: "US 8",
      brand: "Nike"
    }
  ]
})

Example JSON

{
  "id": "7812087d-d7ff-46d7-a790-eb60c4bb679f",
  "model": "Others You May Like",
  "products": [
    {
      "id": "23489023",
      "sku": "23489023",
      "name": "Red Shoes",
      "categories": [
        "Shoes & Accessories > Shoes",
        "Shoes & Accessories > Shoes > Women Shoes"
      ],
      "price": 49.95,
      "quantity": 1,
      "url": "https://example.com/products/23489023",
      "imageUrl": "https://example.com/products/23489023.jpg",
      "currency": "USD",
      "variant": "Striped",
      "color": "Red",
      "size": "US 8",
      "brand": "Nike"
    }
  ]
}

• id - Represents the unique identifier for the recommendation result. The same identifier should be used for recommendation events that relate to the same result. E.g. "Recommendation Viewed", "Recommendation Clicked", "Recommendation Purchased" etc.

• products - All the products that we viewed/clicked/purchased in the recommendation.

• model - The name or type of the recommendation model used.

Targeting

An object representing details related to Fanplayr Targeting.

• Attribute Key - $targeting

Interface

interface Targeting {
  offerId?: string
  experimentId?: string
  actionId?: string
}

JavaScript API

fp360.track('AN_EVENT', {
  $targeting: {
    offerId: 'fp-12345',
    experimentId: 'fp-54321',
    actionId: 'fp-92827'
  }
})

Example JSON

{
  "offerId": "fp-12345",
  "experimentId": "fp-54321",
  "actionId": "fp-92827"
}

Widget

An object representing an individual widget.

• Attribute Key - $widget

Interface

interface Widget {
  id?: string
  name?: string
  variant?: string
  breakpoint?: string
  action?: string
  revisionId?: string
  language?: string
}

JavaScript API

fp360.track('AN_EVENT', {
  $widget: {
    id: 'fp-12345',
    name: 'MyWidget',
    variant: 'Variant1',
    breakdpoint: 'p',
    revisionId: 'revision-5',
    action: 'click',
    language: 'en'
  }
})

Example JSON

{
  "id": "fp-12345",
  "name": "MyWidget",
  "variant": "Variant1",
  "breakdpoint": "p",
  "revisionId": "revision-5",
  "action": "click",
  "language": "en"
}

UTM

An object representing details related to UTM parameters.

• Attribute Key - $utm

Interface

interface UTM {
  id?: string
  medium?: string
  source?: string
  term?: string
  campaign?: string
  content?: string
}

JavaScript API

fp360.track('AN_EVENT', {
  $utm: {
    id: '123xyz',
    medium: 'social',
    source: 'instagram',
    term: 'deal on shirts',
    campaign: 'summer sale 2022',
    content: 'sign up'
  }
})

Example JSON

{
  "id": "123xyz",
  "medium": "social",
  "source": "instagram",
  "term": "deal on shirts",
  "campaign": "summer sale 2022",
  "content": "sign up"
}

Page

Details related to the page view associated with the event.

• Attribute Key - $page

Interface

interface Page {
  name?: string
  path?: string
  referrer?: string
  title?: string
  type?: string
  url?: string
}

JavaScript API

fp360.track('AN_EVENT', {
  $page: {
    name: 'Red Shoes',
    path: '/product/123',
    referrer: 'https://store.com/pages/123',
    title: 'Homepage',
    type: 'Product',
    url: 'https://store.com/product/123'
  }
})

Example JSON

{
  "name": "Red Shoes",
  "path": "/product/123",
  "referrer": "https://store.com/pages/123",
  "title": "Homepage",
  "type": "Product",
  "url": "https://store.com/product/123"
}

Device

Details related to the device that generated the event.

• Attribute Key - $device

Interface

interface Device {
  browser?: string
  browserMajorVersion?: number
  browserMinorVersion?: number
  city?: string
  continent?: string
  country?: string
  countryCode?: string
  family?: string
  ipAddress?: string
  latitude?: number
  longitude?: number
  os?: string
  osMajorVersion?: number
  osMinorVersion?: number
  postalCode?: string
  region?: string
  regionCode?: string
  timezone?: string
  type?: string
  userAgent?: string
}

JavaScript API

fp360.track('AN_EVENT', {
  $device: {
    browser: 'Firefox',
    browserMajorVersion: 17,
    browserMinorVersion: 3,
    city: 'Palo Alto',
    continent: 'North America',
    country: 'United States',
    countryCode: 'US',
    family: 'Mobile',
    ipAddress: '127.0.0.1',
    latitude: 37.441670,
    longitude: -122.160650,
    os: 'macOS',
    osMajorVersion: 12,
    osMinorVersion: 6,
    postalCode: '94306',
    region: 'California',
    regionCode: 'CA',
    timezone: 'America/Los_Angeles',
    type: 'Mobile',
    userAgent: 'Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0',
  }
})

Example JSON

{
  "browser": "Firefox",
  "browserMajorVersion": 17,
  "browserMinorVersion": 3,
  "city": "Palo Alto",
  "continent": "North America",
  "country": "United States",
  "countryCode": "US",
  "family": "Mobile",
  "ipAddress": "127.0.0.1",
  "latitude": 37.44167,
  "longitude": -122.16065,
  "os": "macOS",
  "osMajorVersion": 12,
  "osMinorVersion": 6,
  "postalCode": "94306",
  "region": "California",
  "regionCode": "CA",
  "timezone": "America/Los_Angeles",
  "type": "Mobile",
  "userAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0"
}

Session

An object representing a browsing session.

• Attribute Key - $session

Interface

interface Session {
  domain?: string
  durationSecs?: number
  endTime?: string
  id?: string
  orderCount?: number
  pageCount?: number
  startTime?: string
}

JavaScript API

fp360.track('AN_EVENT', {
  $session: {
    domain: 'demo.fanplayr.com',
    durationSecs: 20,
    endTime: '2000-01-01 10:30:00',
    id: "asdfasdfasdf"
    orderCount: 0,
    pageCount: 5,
    startTime: '2000-01-01 10:29:40'
  }
})

Example JSON

{
    "domain": "demo.fanplayr.com",
    "durationSecs": 20,
    "endTime": "2000-01-01 10:30:00",
    "id": "asdfasdfasdf"
    "orderCount": 0,
    "pageCount": 5,
    "startTime": "2000-01-01 10:29:40"
}