SEEK Developer

This content is still in draft.

SEEK provides an Ad Performance Panel you can embed within your software to help hirers understand how each job ad is performing. The widget displays job search views, job ad clicks, application starts and application completes. It can also provide insights such as market performance, benchmarked against ads posted with similar job titles and locations.Application completes will be visible for:

Job ads using Optimised Apply, where candidates complete SEEK’s Apply Form.
Job ads using an external apply form, if the candidate arrived from SEEK.This is derived from application complete signals where the candidate source is SEEK. It does not include scenarios where the candidate arrived from another source but used Apply with SEEK.

Your software must send an application complete signal along with the Ad Performance Panel if it supports posting job ads that link out to an external apply form.

User experience

The Ad Performance Panel is designed to present data for a single job ad on SEEK. To ensure relevance and context, it should be displayed in a view that directly corresponds to the specific job. For instance:

Within the “Job Details” view for a specific position
Alongside existing metrics for an individual job
As part of a job list, accessible via a button that reveals the panel in a pop-up

The Ad Performance Panel must be available to hirers for at least the duration of the position opening, and will continue displaying data as long as the PositionProfile remains available, as per the job ad lifecycle. In the event that ad performance data for a requested job ad is unavailable, the panel will manage any errors internally and display appropriate messaging to the hirer.To maintain clarity, we recommend against displaying multiple instances of the Ad Performance Panel on the same page.

Browser support

The Ad Performance Panel tracks our standard browser support policy.

Step 1: Include the panel

Add the following script tag to the page where the Ad Performance Panel will be displayed:

HTML

Copy

<script

  type="text/javascript"

  src="https://integration.seek.com/panels/SeekApi.js"

></script>

Step 2: Render the panel

The SeekApi.render function renders an instance of the panel in the specified DOM element, and should be called on page load or if the currently viewed job ad changes.The render function may throw errors if:

The containerNode provided is not a valid HTMLElement

JavaScript

Copy

SeekApi.render(containerNode, 'adPerformance', props);

containerNode – (DOM Node) The DOM element to render the panel into.
'adPerformance' - The name of the panel to render.
props – Props for rendering the panel.

Modifying the containerNode or its children after the render function has been called may lead to unexpected behaviour.

Props

Prop	Type	Description
`getAuthToken`	`() => Promise<string>`	Function to call to retrieve the browser token to use when calling the SEEK API.
`positionProfileId`	`string`	The identifier of the job ad to be displayed.
`locale`	`string`optional	Specifies the locale to display content in, e.g. `en-AU`. Supported locales are outlined in the content localisation documentation.

Sample code

JavaScript

Copy

SeekApi.render(

  document.getElementById('seekAdPerformanceContainerDiv'),

  'adPerformance',

    // Function to call to retrieve the browser token to use when calling the

    // SEEK API, see "Step 3" for more details.

    getAuthToken: () => {

      return Promise.resolve('browser token');

},

    // Object identifier for the job ad to be displayed.

    positionProfileId: 'seekAnzPublicTest:positionProfile:jobAd:2782PZfXV'

);

Step 3: Handle browser token requests

The panel loads and executes the getAuthToken function passed to it.
Your frontend requests a browser token from your backend.If a user switches to a job ad from a different SEEK hirer account, your software should ensure that subsequent invocations of getAuthToken will request a token for the new hirer ID before re-rendering the panel.
Your backend authenticates and authorizes the user.Your software is responsible for verifying that the user is authorized to access a given hirer ID and view performance data for their job ads. A user must not be able to request a browser token for an arbitrary organization that they do not belong to.
Your backend requests a browser token from the SEEK API for the appropriate hirer ID and query:advertisement-performance query:position-profiles query:ontologies scopes.

HTTP

Copy

POST https://graphql.seek.com/auth/token HTTP/1.1

Authorization: Bearer PARTNER_TOKEN_HERE

Content-Type: application/json

User-Agent: YourPartnerService/1.2.3

  "hirerId": "seekAnzPublicTest:organization:seek:93WyyF1h",

  "scope": "query:advertisement-performance query:position-profiles query:ontologies",

  "userId": "317665"

Your backend responds with the browser token.
Your frontend returns the browser token from the getAuthToken function.
The panel completes initialising and displays the relevant ad performance data.

Testing

Job ads created by a test hirer account do not show their ad performance data in the panel. For these test hirers, the panel displays an error that data is not available for the job ad.To verify your panel integration is functioning as expected, you can instead post a job with the position title [TEST PANEL]. Viewing ad performance for a job with this title will display mock data.

Troubleshooting

See our general panel troubleshooting documentation for more information.

Ad Performance: Application complete signal

Use cases: Talent Search Connect