Quikly Drop

Quikly Drop campaigns feature a finite amount of rewards and/or offers awarded by rank, elapsed time, or randomly.

Drop campaigns are made up of a main screens with three different stats, and one additional component that displays offer details after claiming.

Overview

The basic concept for a Drop campaign is to send a viewer’s email address to attempt to claim an offer. If successful, the API returns a unique receiptToken that can be used to fetch offer details, as well as an authToken for the user to be used in subsequent API calls to provide authenticated access on that user’s behalf.

Additional fields in the API provide CMS-like data that is helpful when rendering a campaign, including headings, images, fine print, and offer details.

Offer Screen

Use the following query to fetch the content for the initial screen of the campaign. In this way the API acts as a CMS so that a campaign manager can update the promotion titles, fine print, and images from the Quikly admin interface.

query promoLandingQuery($dealHashid: String!) {
  quikly(hashid: $dealHashid) {
    id
    name
    description
    header: customContentFor(key: "embedded_instant_sign_in_header")
    finePrint
    buttonText: customContentFor(key: "embedded_instant_sign_in_button_text")
    image {
      url(variant: "original")
    }
  }

The quikly type refers to the campaign instance.

Claiming an Offer

To claim an offer, send the user’s email address to the createEmbeddedClaim mutation. This returns a unique offer identifer (qid) and receiptToken used to securely fetch offer details, as well as the user’s authToken which can then be used to identify this user on subsequent interactions with the API via the authorization header.

mutation createEmbeddedClaim(
  $dealHashid: String!
  $email: String!
) {
  createEmbeddedClaim(
    input: { dealId: $dealHashid, email: $email }
  ) {
    errors {
      key
      message
    }
    user {
      id
      authToken
    }
    order {
      id
      qid
      receiptToken
    }
  }
}

You should store the order’s qid, receiptToken and the user’s authToken locally.

Fetching Offer Detail

Use the getOrder query to fetch offer details for a user once they have successfully claimed.

query getOrder($orderId: Int!, $receiptToken: String!, $dealTierId: Int) {
  order(
    orderId: $orderId
    receiptToken: $receiptToken
    dealTierId: $dealTierId
  ) {
    id
    qid
    expirationDate
    itemFullDescription
    itemInstructions
    finePrint
    codes: codesWithLabelsAndBarcodes {
      instore
      pin
      value
      label
    }
    links {
      id
      name
      url
      position
    }
    quikly {
      id
      hashid
      termsUrl
      congratsMessage: customContentFor(key: "claim_congrats")
      congratsHeader: customContentFor(key: "claim_congrats_embedded_header")
      congratsSubheader: customContentFor(
        key: "claim_congrats_embedded_subheader"
      )
      redeemCopy: customContentFor(key: "embed_redeem_body")
    }
  }
}

This example shows how you can fetch content from the Quikly campaign (such as a congrats message or campaign heading) as well as data tied to the individual’s offer: one or more offer codes, an expiration date, associated fine print or redemption urls, and more. At this point, referencing the OrderType in the GraphiQL Explorer will be very useful!

Checking Claim Status

A quick way to check if a currently authenticated user has already claimed an offer is to use the alreadyClaimed field on the wantIn type:

query checkAlreadyClaimed($dealHashid: String!) {
  quikly(hashid: $dealHashid) {
    id
    wantIn {
      id
      alreadyClaimed
    }
  }
}

The wantIn type represents the viewer’s opt-in to a campaign (stemming from the phrase “I Want In”). It ties a user to a quikly.