Ad selection with GraphQL

This document explains how to build your own user interface to display and select ad products. Available ad products can be programmatically retrieved by your software when posting or updating a job ad.Building your own panel can be broken down into four tasks: gathering user input, querying ad products, rendering the panel, and handling user selections.

Before you begin

  • Evaluate whether you can embed the SEEK-built Ad Selection Panel, which is a simpler alternative to creating your own implementation.
  • SEEK recommends using a browser token to query ad products directly from a hirer’s browser. For the browser token to work, you will need to include the query:ad-products scope in your request.
  • You can also query ad products from your backend using a partner token.

Gathering user input

positionProfile

For your convenience, the structure of the positionProfile input subsets the input to the postPosition and postPositionProfileForOpening mutations.jobCategories, positionLocation, and positionOrganizations currently accept a single element. When creating a job ad, your software must omit the optional profileId field. When updating a job ad, your software must provide its profileId.We recommend rendering ad selection after you capture salary information in your posting workflow. This will enable your software to supply the optional offeredRemunerationPackage and seekAnzWorkTypeCode inputs to ad selection, which SEEK can use to better predict—and inform the user of—how each ad product is likely to perform.

selectedAdvertisementProductId

If a job ad has been saved as a draft in your software but has not been posted, the ad product selected by the user may become stale and its associated price may no longer be honoured. You should refresh product IDs that you have temporarily stored against job ad drafts. When loading a draft job ad into a user interface for submission, you should provide the saved product ID as selectedAdvertisementProductId.

Querying ad products

The advertisementProducts query allows you to retrieve ad products when posting or updating a job ad.This query must be executed on page load and whenever the properties of the positionProfile input change. For example, if the hirer selects a new location, you must re-render the panel to reflect updated products and pricing.
QueryVariablesResult
CopyGraphQL Explorer
query advertisementProducts(
  $positionProfile: AdvertisementProducts_PositionProfileInput!
  $selectedAdvertisementProductId: String
) {
  advertisementProducts(
    positionProfile: $positionProfile
    selectedAdvertisementProductId: $selectedAdvertisementProductId
  ) {
    products {
      id {
        value
      }
      label
      description
      sellingPoints {
        text
      }
      price {
        summary
      }
      selected
      features {
        branding {
          coverImageIndicator
          logoIndicator
        }
        searchBulletPoints {
          limit
        }
      }
      payment {
        summaryHtml
      }
    }
    information
  }
}

Rendering the panel

The result of the advertisementProducts query should be presented to the user for selection. Now, your interface must be capable of displaying a variable number of ad products, typically between 1 and 4. If there is a hard limit to the number of ad products that you can display, you must provide a limit to the query so that SEEK can provide the most relevant set of products within your constraints. Do not manually truncate the returned list as that may exclude highly relevant products.We’ve included a recommended design for your ad selection interface below. You can hover over the field descriptions to see which part of the interface they correspond to.
Classic
products[].label 3

AUD 269.89

products[].price.summary 4
Find great candidates with our basic ad
products[].description 5
  • 30 day listing on SEEK
  • Your job ad emailed to relevant candidates
products[].sellingPoints 6
Branded
products[].label 3

AUD 364.59

products[].price.summary 4
Stand out with branding and key selling points
products[].description 5
  • Logo and cover image to promote your brand
products[].sellingPoints 6
Premium
products[].label 3

AUD 645.00

products[].price.summary 4
Attract more candidates on average with a featured listing
products[].description 5
  • Priority listing in search
products[].sellingPoints 6
products 1
Ad prices vary based on many factors including the supply of, and demand for, candidates for the advertised role. Prices shown represent today's prices only. If you schedule your job ad for a future date, you acknowledge and agree you'll be charged the price of that ad at the date it's published on SEEK's website.
information 7
products[].payment.summaryHtml 8
products[].features 9
  1. productsDisplay products in the returned list order. We recommend a tile layout.
  2. products[].selectedPre-select the product with a selected indicator set to true. If all indicators are false, then no ad product should be selected by default.This is typically returned when you provide positionProfile.profileId to update a job ad or selectedAdvertisementProductId to restore the previous selection of a job ad draft.
  3. products[].labelDisplay the label as the headline of the product.
  4. products[].price.summaryDisplay the price summary after the label. If the price is null, do not display a price.
  5. products[].descriptionDisplay the description after the price summary.
  6. products[].sellingPointsDisplay the selling points alongside the product. We recommend an unordered list of the inner texts.
  7. informationDisplay informational text below the products. This field must be dynamically retrieved from the response as it may contain tailored legal disclaimers.
  8. products[].payment.summaryHtmlConditionally display the payment summary below the products. This field should only be displayed when a product is selected.If rendering HTML is impractical for your software, you may use the plain-text summary instead.
  9. products[].featuresConditionally display subsequent fields to select a brand or enter search bullet points on the job posting form. Each field should only be displayed when a product is selected and the corresponding feature is supported by the selected product.

Managing variable job ads

Due to the variable nature of SEEK’s product ladder, the GraphQL query return ephemeral product IDs that reference the set of products quoted at that point in time. When a hirer selects a product and your software propagates its identifier to post or update a job ad, SEEK will scan recent ad selection contexts for a match and attempt to lock in the exact quoted product features and pricing.Ad products presented to a hirer are only valid within the context of the workflow that they were executing at the time. Product IDs cannot be persisted long term; they should not be stored alongside a posted job ad for subsequent update workflows or to otherwise build a hardcoded mapping.

Handling drafts

The selected product ID may be temporarily stored in a job ad draft. When the hirer resumes their posting workflow from the draft at a later date, this previous product ID must not be directly used to post the job ad. Instead, pass the previous product ID to the advertisementProducts query as the selectedAdvertisementProductId. The query will then pre-select an equivalent ad product and return new product IDs that can be used to post the job ad.

Handling edits

When a hirer edits an existing job ad, the profileId of the job being updated must be included as part of the positionProfile in your call to the advertisementProducts query. This ensures the correct ad products and pricing are returned.The returned AdvertisementProducts may include a product marked as selected. This product should be shown as selected in your interface, and the product ID persisted in memory as the currently selected ad product.The returned AdvertisementProducts may also include products with a null price. Any products with a null price must be displayed in your interface without any price information. These could represent products where there is no charge applicable, or products where the SEEK hirer account has been configured to hide price information.Additionally, the product ID used to initially post the job ad must not be used again when calling updatePostedPositionProfile. Instead, only use a product ID returned from the most recent advertisementProducts query.Ensure that your software follows our guidance on rendering the panel and dynamically displays the information field. When a job ad is expired, this will display a note that further edits are no longer possible.

Stale product ID errors

When executing mutations such as updatePostedPositionProfile, you might encounter errors similar to:
JSON
Copy
{
  "errors": [
    {
      "message": "Invalid posting instructions",
      "extensions": {
        "code": "BAD_USER_INPUT",
        "invalidFields": {
          "/input/positionProfile/postingInstructions/0/seekAdvertisementProductId": "No longer valid; refresh the available ad products for this job ad"
        }
      }
    }
  ]
}
This can indicate an underlying implementation issue, for instance:
  1. A product ID from a draft has been stored for too long and was used to post the job ad.
  2. A product ID used to initially post a job ad has been used again to update the ad.
  3. The panel was rendered without a profileId when editing an existing job ad, resulting in the selected product ID being invalid for an update.
To resolve these scenarios, check that all job posting flows refresh the product ID correctly prior to posting. This can be achieved by calling advertisementProducts during an edit or draft refresh (including the profileId for existing ads). Ensure to use only a product ID returned from that call in the mutation to post or update the job ad.

Handling user selections

When a hirer selects an ad product, your software should conditionally display form inputs for the additional job ad features it enables. See features for ad products for a detailed walkthrough.The selected product id should be persisted in memory. When the hirer is ready to create or update the job ad, provide the identifier in the posting instruction seekAdvertisementProductId field on the postPosition, postPositionProfileForOpening or updatePostedPositionProfile job posting mutations.
Ad selection: Option 1: Panel
Ad selection: Features