npm package: @jobortunity/jobfie-button
Description: <div align="center">   <img align="center" width="180" src="https://jobortunity.be/assets/logo-jobortunity-green.png" /> </div>
Author: Jobortunity BVBA
Latest version: 1.0.2

<div align="center">
  <img align="center" width="180" src="https://jobortunity.be/assets/logo-jobortunity-green.png" />
</div>

# Jobfie button

>Integrate the power of a Jobfie into your own application forms!

With the Jobfie button you can expand your current online application form with video resumes. When initializing the Jobfie button, you also give in 1 to maximum 3 questions to which you want a 30 seconds video answer (we call this a "Jobfie"). For more info: see Jobfie button initialisation.

E.g.: your current online application form acceps following fields:
 - First name
 - Last name
 - E-mail
 - Phone
 - Resume

When the applicant filled in these fields, they will be submitted to your system for further processing, e.g. of submission with FormData:

```javascript
var data = new FormData();
data.append("firstname", firstname);
data.append("lastname", lastname);
data.append("email", email);
data.append("phone", phone);
data.append("resume", resume);
//POST data;
```

By adding the Jobfie button to your form, it will only change the data submitted to your system. Visually there will no change to your form, except the presence of the Jobfie button ofcourse (but this can be positioned wherever you like).

When an applicant has succesfully filled in one or more Jobfies for your form, your application (in which the Jobfie button is incorporated) will receive these Jobfie(s) in the form of an array together with the questions you asked. For example: you initialize the Jobfie button with following questions:
```json
[
	"How well do you work in a stressful environment?", 
	"Are you a solo or team player?"
]
```
You will receive following array as a result: 
```json
[
	{
		question: "How well do you work in a stressful environment?", 
		answer: "https://.../jobfie-1.mp4"
	}, 
	{
		question: "Are you a solo or team player?", 
		answer: "https://.../jobfie-2.mp4"
	}
]
```
How you progress this array is fully up to you! Say you only ask 1 question but don't need to send a whole array of these to your system, e.g.:
```javascript
//De array met de vragen en Jobfie-antwoorden
var result = theJobfieArrayResult;
var data = new FormData();
data.append("firstname", firstname);
data.append("lastname", lastname);
data.append("email", email);
data.append("phone", phone);
data.append("resume", resume);
data.append("question", result[0].question);
data.append("answerLink", result[0].answer);
//POST data;
```
## Installation Jobfie button library
You can install the Jobfie button library with NPM:
```bash
npm install @jobortunity/jobfie-button
```
Make sure to reference the css and js file of the jobfie-button inside your project!

## Jobfie button initialisation
Make sure your HTML has a placeholder for the Jobfie button, e.g: 
```html
<div  id="jobfie-container"></div>
```
In your client code you can then initialise the Jobfie button with following Javascript:
```javascript
import  JobfieButton  from  'jobfie-button';
...
let  jobfieBtn = new  JobfieButton({
	querySelector:  "#jobfie-container",
	apiKey:  "your-generated-key",
	onJobfieRecorded:  function(result) {
		//callback when Jobfie was successfully recorded.
		//result is array of object {question: "What is this question?", answer: "https://the-jobfie-url.com"}
		let  first = result[0];
		let  question = first.question;
		let  answerVideoUrl = first.answer;
	}
});
...
//Set the candidate and job.
jobfieBtn.candidate.firstName = "John";
jobfieBtn.candidate.lastName = "Doe";
jobfieBtn.candidate.email = "john.doe@example.org";
jobfieBtn.candidate.phone = "0489554466"; //NOTE: fill in phone without county code. In current stage +32 is automatically prefixed!
jobfieBtn.job.id = "internaljobid";
jobfieBtn.job.name = "Cool job!";
jobfieBtn.job.questions = ["One example question?"];
```
Also make sure you have a valid API key. You can create these via: [
Jobfie plug & play](https://www.jobortunity.be/nl-BE/werkgevers/nieuwe-jobfie-integratie).

## Jobfie button styling
Since the Jobfie button is rendered within your code, it will automatically also inherit your button's styling. If you want to add specific styling to the button (or the button isn't inheriting your styling because you use specific classes, e.g. Bootstrap), then you can style the button by using the class "btn-jobfie". All buttons within the Jobfie button container use these class. E.g.:
```css
button.btn-jobfie {
  background: none;
  border: 2px solid #16a085;
  color: #16a085;
  padding: 15px;
}

button.btn-jobfie:hover {
  background: #16a085;
  color: white;
  cursor: pointer;
}
```
If you already make use of SASS, you can easily make the button inherit styling of your existing buttons by using **@extend**. E.g.:
```scss
button.btn-jobfie {
	@extend .btn;
	@extend .btn-primary;
}
```

## Jobfie button options
Following options are available on the Jobfie button:
```javascript
//Constructor takes settings as parameter
let jobfieButton = new JobfieButton({
	  apiKey: "my-generated-key", //required, Jobfie plug & play API key
	  querySelector: ".jobfie-btn", //optional, the query selector for the container holding the Jobfie button, default: ".jobfie-btn"
	  //localization:
	  locale: "nl", //optional, default: "nl", supported locales are "nl", "fr" and "en"
	  //For custom texts of the buttons
	  buttonGenerateAppLinkText:"", //optional, default: "Genereer Jobfie app link"
	  buttonAppLinkText:"", //optional, default: "Open de app"
	  buttonText:"", //optional, default: "Jobfie opnemen"
	  buttonTextMeTheAppText:"", //optional, default: "SMS mij de app"
	  buttonContinueInAppText:"", //optional, default: "Ga verder in de app"
	  buttonJobfieRecordingText:"", //optional, default: "Jobfie wordt opgenomen"
	  buttonJobfieRecordedText:"", //optional, default: "Jobfie opgenomen"
	  //callbacks:
	  onSessionStarted: function(sessionId){
		//result is the id of the current session
	  },//callback: the session was started
	  onJobfieRecorded: function(result){
	    //result is an array containing your submitted questions with the answers of the applicant (as urls)
	    //result[0].question => one of your questions
	    //result[0].answer => the Jobfie of the application (as url)
	  },//callback: the Jobfie was succesfully recorded on the app
	  onJobfieRecording: function(){}, //callback: the Jobfie is recording. This is called when the applicant is starting his recording.
	  onError: function(message){
		//possible values for message:
		//JOBFIEBTN_APICONNECTION_ERROR: error result from the Jobortunity API, check developer console for more info
		//JOBFIEBTN_APIKEY_ERROR: no API key present in settings
		//JOBFIEBTN_DOM_ERROR: querySelector not found
		//JOBFIEBTN_BRANCHSMS_ERROR: could not send sms
		//JOBFIEBTN_DISABLEPOPUPBLOCKER_ERROR: could not open send desktop SMS page due to popup blocker. Disable popup blocker!
	  } //callback: something went wrong with the Jobfie button.
  });
# the candidate object //required
jobfieButton.candidate = {
    firstName: "John", //required
    lastName: "Doe", //required
    birthDate: new Date(), //optional
    email: "john.doe@example.org", //required
    phone: "0478554455" //optional, but will be asked by an inline form inside the Jobfie button container if this value is undefined/null. Note: no country code!
  };
  
# the job object //required
jobfieButton.job = {
    id: "my internal job id", //required, internal id reference to your job
    name: "Lovely job in our lovely company", //required, reference to you job by name
    questions: ["Can this hold multiple questions"] //required, one to maximum 3 questions (string array). Note: if more than 3 questions, only first 3 will arrive in the app.
};

# change locale //this will re-render the button
jobfieButton.changeLocale("en");
```
## Jobfie button: flow
*Note: the default text on the button is Dutch*
When the Jobfie button is loaded onto the page, the applicant  will see the button "Jobfie opnemen". If the field **phone** of the *candidate* object is filled in, then a text message will be directly send to that phone number. If the phone is not filled in, an intermediary form will come up, asking the phone number of the applicant. In this form, the applicant fills in the phone number and presses "SMS mij de app". After successfully sending the text message, the button will change into "Ga verder in de app". The applicant continues in the app en records one or more Jobfie(s) (depending on the amount of questions asked). The moment the applicant starts the recording, the button on the form will change to "Jobfie wordt opgenomen". As soon as all Jobfies are recorded and submitted in the app, the button on the form will change to "Jobfie opgenomen", after which the callback **onJobfieRecorded** is called, in which you will find the array of questions and the Jobfie answers (as URLs). 

## Notes
Eventhough there isn't much to be implemented on your application for integrating the Jobfie button, do not forget the extra fields that will be submitted to your system! These must be progressed and saved properly on your system!

## FAQ
The buttons keeps loading or isn't showing in my application?

> Open the developer console (F12) and see if there are any error messages or warnings. These will be explained in this FAQ further on. Still can't get the Jobfie button working? Contact us on support@jobortunity.be.

I get the warning **"Invalid license"** in the developer console (F12) of my browser? 

> This means you don't have access to Jobfie plug & play or that this license isn't valid anymore. Contact us on support@jobortunity.be.

I get the warning **"Invalid key"** in the developer console (F12) of my browser?

> This points to an invalid API key. Perhaps you are using an old one or a non-existent key? Check your API key on the dashboard of the Jobfie plug-ins: https://www.jobortunity.be/nl-BE/werkgevers/jobfie-integraties.

I get the warning **"Domain not allowed"** in the developer console (F12) of my browser?

> Double check the domain inside your Jobfie plug-in on the Jobfie plug & play dashboard. Is it the same as the domain of the application you are integrating the Jobfie button on? Perhaps you used *http* instead of *https*?