Module 2 - Apply with LinkedIn Plugin

Article
05/17/2023

Refer to the below sections for a step by step guide to integrate the Apply With LinkedIn plugin onto your job application page

Step 1 - Allowlist JS Domains
Step 2 - Deploy and Configure the Plugin

Step 1 - Allowlist JS Domains

To ensure that other applications cannot fraudulently represent themselves as your own using the JavaScript SDK, you must configure a list of valid domains on your application that LinkedIn is allowed to trust. Ensure that you include fully qualified domain names, including the protocol (i.e. http, https) and any non-standard port numbers (other than ports 80 or 443). The way you can update/add valid domains depends on if you are a partner who provides an ATS for multiple customers or a partner who owns a proprietary ATS or career page solution.

For Customers (i.e. proprietary ATS or career page solution)

Add your domain(s) to the Valid SDK Domains field in your application's settings page under JavaScript tab as shown below:

Javascript API Domains

For Partners (e.g. ATS)

Update the valid JS domains for each child app using the endpoint documented here .

Note

Failure to allowlist JS Domain will result in an error to your browser whenever you try to load the plugin.

Step 2 - Deploy and Configure the Plugin

To use any of the functionality provided by the "Apply With LinkedIn" plugin, it must be deployed and loaded on your career site’s web page. Based on the plug-in, the setup may vary for each page where the plugin needs to be added. We do not support JavaScript customization of AWLI button and events.
The setup is to identify the user who clicked apply, prefilling profile information, or providing application completion information back to LinkedIn. However, there are slight differences in the parameters to invoke the plugin and the callback to handle the response.

javascript

<div name="widget-holder"
<script type="text/javascript"
 src="https://platform.linkedin.com/xdoor/scripts/in.js">
 api_key: {customer app API Key goes here}
extensions:AwliWidget@https://www.linkedin.com/talentwidgets/extensions/apply-with-linkedin-widget-v3
</script>
<script type="IN/AwliWidget"
  data-mode="{BUTTON_DATA or CONVERSION}"
  data-integration-context="urn:li:organization:{id}"
  data-company-job-code=”{UniqueJobCode}”
  data-callback-method=”handleProfileData”>
</script>
…
</div>

Plugin Parameters

The table below explains all plugin parameters that can be configured as required:

Name	Required	Description
api_key	yes	API key (Client ID) for your application
data-company-job-code	yes	Unique job posting id within the company's system. This value is used by LinkedIn to identify the job and for tracking purposes. If you use other integrations like RSC, PJP, AC to sync jobs to LinkedIn please ensure that this field is same as `externalJobPostingId` in Job Posting Schema
data-integration-context	yes	A value in the format of `urn:li:organization:{ID}`, ATS partners will retrieve this after the customer has logged in to the customer configuration plugin. Customers directly integrating with AWLI can refer to this help center article to find their company ID for `urn:li:organization:{ID}`
data-mode	yes	The mode in which this plugin will be used. Currently, the following two modes are supported: 1.BUTTON_DATA Mode- Creates the Apply With LinkedIn button on the page and starts the click tracking within LinkedIn. Once applicant clicks this button and consents to sharing profile data, data is shared with partner using the callback method 2.CONVERSION Mode- No visible items are created on the page. A conversion tracking event is sent back to LinkedIn to track the application status of the member. Note that the user must click the Apply With LinkedIn button on the previous page to track this conversion
data-callback-method	no	The callback method that will be called when there is communication required between the plugin and the client. Depending on the mode that is configured, different callback methods will be required. 1.BUTTON_DATA Mode- Specify the actions to take after the plugin button is clicked and the applicant’s profile data is received from LinkedIn. 2.CONVERSION Mode- Callback not required. For BUTTON_DATA mode, the tracking events/profile data fetch action on the LinkedIn side will still be triggered even if a callback is not provided
data-size	no	Acceptable values are small, medium or large. The default value is medium. For reference, the size of the button is as follows: 1. Small - width: 188px, height: 32px 2. Medium - width: 213px, height: 48px 3. Large - width: 233px, height: 48px
data-color	no	Acceptable values are blue, black or white. The default value is blue

UI Rendering

Below are various ways in which the Apply with LinkedIn button can be rendered (check table above for exact data-size values for different sizes):

Size	Button Rendering
Small
Medium
Large

If the applicant is not signed to LinkedIn in the current browser session and has no browser cookie present, the below sign in screen appears for the applicant when they click on Apply With LinkedIn button.

notsignedin

Once signed in with LinkedIn credentials, LinkedIn displays a different OAuth consent screen for regular customers v/s Search and Staff agencies (customers who use profile info across multiple jobs) as shown below:

module2 nonstaffing

module2 staffing

Integration Walkthrough

Please check video here to learn how to integrate Apply with LinkedIn plugin.

Plugin Error Details

Click to view Plugin Errors

For plugin error details, look into browser-developer-tool console log for any error message:

Error Message	Description	Resolution
error.origin.not.in.api.domains	The Partner Domain URL is not allowlisted for your application.	1.Update `validJsSdkDomains` for your application. 2. Ensure `validJsSdkDomains` should not contain trailing slash (/) 3. Ensure `validJsSdkDomains` should contain complete URL and should start with http and https
error.ats.integration.not.valid	The value provided in the plugin parameter `data-integration-context` is invalid	1. Ensure that you are using correct integration context. It should be a company urn and will look like `urn:li:organization:xxxxx`. Follow below steps if you are using correct integration context: 1.a For Partners (e.g. ATS) - Make sure Enable Customer Integration API is called after you have received the integration context. Please refer to Step 3 in the ATS Integration documentation. 1.b For Customers (i.e. proprietary ATS or career page solution). Please ask for assistance from your LinkedIn point of contact
error.finding.application.with.api.key	Invalid API key used	Make sure you are using the correct api key
error.deprecated.mode	Deprecated mode value used eg BUTTON, DATA	Valid modes to use - BUTTON_DATA or CONVERSION
error.application.not.approved	The application is not in approved status	Please reach out to our support team via Zendesk
error.unknown.mode	Incorrect mode value used	Make sure you use with BUTTON_DATA or CONVERSION mode
error.unknown	Unknown error	Please reach out to our support team to troubleshoot the issue
error.missing.origin.referer.headers	Web browsers automatically pass the origin and referer header. If partners or customers configure their application in a way that these headers are not passed (such as configuring referer header policy), then the widget cannot validate the domain for which it is embedded	Origin or referer header must be passed for the Apply with LinkedIn widget to work

Sample Profile Data Response

If the member is LinkedIn authenticated and authorized (via OAuth authorization flow), and the plugin is configured in BUTTON_DATA mode, we fetch the member’s profile data and pass it back to the partner’s page. Depending on the implementation, the data can be used to help fill the application form. The application needs to create a callback method to handle this data returned from LinkedIn.
A sample response is shown below:

“profileData”:
{
  "firstName": "FirstName",
  "lastName": "LastName",
  "headline": "Software engineer at LinkedIn Corporation",
  "summary": "This is my Summary.",
  "location": {
    "locationName": "San Francisco Bay Area",
    "country": "us"
  },
  "publicProfileUrl": "www.linkedin.com/in/firstname-lastname-123",
  "positions": [
    {
      "title": "Software Engineer",
      "summary": "Software development",
      "startDate": null,
      "endDate": null,
      "isCurrent": true,
      "companyName": "LinkedIn Corporation",
      "company": {
        "name": "LinkedIn",
        "type": "EDUCATIONAL"
        
      }
    },
    {
      "title": "abc",
      "summary": null,
      "startDate": {
        "month": 1,
        "year": 2011
      },
      "endDate": {
        "month": 2,
        "year": 2013
      },
      "isCurrent": false,
      "companyName": "nonexistingcompany",
      "company": null
    }
  ],
  "skills": [],
  "educations": [
    {
      "schoolName": "University of Pennsylvania",
      "fieldOfStudy": "Computer Science",
      "startDate": {
        "year": 2016
      },
      "endDate": {
        "year": 2020
      },
      "degree": "Master of Engineering (MEng)",
      "activities": "a brief description to my UPenn activities",
      "notes": "Hanging around"
    }
  ],
  "languages": [
    {
      "name": "English",
      "proficiency": "ELEMENTARY"
    },
    {
      "name": "Chinese (Simplified)",
      "proficiency": "PROFESSIONAL_WORKING"
    }
  ],
  "certifications": [
    {
      "name": "Certified Java Programmer",
      "authority": "Coursera",
      "number": "1233211234-4",
      "startDate": {
        "month": 1,
        "year": 2000
      },
      "endDate": {
        "month": 1,
        "year": 2000
      }
    }
  ],
  "emailAddress": "testuser@linkedin.com",
  "phoneNumber": "123-321-1234",
  “memberIdentifier”: "VuxQHF3ULX"
}
signature: "1f51064ea13176a0ace6c8cb490e884d74e1ddf128f81e3fab8a119055dcc5fb"

Share via

Module 2 - Apply with LinkedIn Plugin

Step 1 - Allowlist JS Domains