ENGAGE HELP CENTER
Longenesis.Engage integration into Partner Portal
This section will be your guide on how to integrate the Engage content into your own website.
How to integrate the Engage content into your own website

Surveys without registration
You can easily integrate Engage surveys that don't require registration into your own website (hereafter called the Partner Portal). The integration is done via iFrame - you decide where in your website you want to display the survey and place the iFrame there. The rendering and processing of the survey is fully covered by Engage - all you have to do is place the iFrame in your website and choose a color palette for the Engage element to blend into the design of you website.

Below is an example of the embed code for the integration.
<iframe 
  src="https://engage.longenesis.com/partner_view?activitySlug=aabbcc" 
  width="100%" 
  height="1200" 
  style="border:none;"></iframe>
In the example, the activitySlug element must be set to the slug of the specific no-registration survey instead of "aabbcc".
The activitySlug of the Engage activity can be found when accessing the Public sharing section of an Engage survey.
Surveys with registration
If you would rather have your participants identified and have them submit surveys with registration, we offer a secure way to seamlessly log your participants into Engage. To use this method, your website must have a server-side component which will be used to authenticate at Longenesis and acquire an access token for your participants. The overall process flow is as follows:

(1) Participant logs into the Partner Portal.
(2) Participant clicks the button to take the survey in the Partner Portal.
(3) Portal authorizes at Longenesis Auth Service and (4) receives access_token for the Portal itself.
(5) Portal posts participant ID to EngageAPI and (6) receives authorization_code for the participant.
(7) Portal instructs its front-end to load https://engage.longenesis.com/partner_view in an IFrame.
(8) Participant submits survey.
More details on the difference between Surveys with and without registration can be found here.
How to authenticate your participant into Engage
Here is a python code example of how to get the authorization_code for the participant.
import requests

AUTH_ENDPOINT = (
    "https://auth.longenesis.com/realms/curator-engage/protocol/openid-connect/token"
)
USERNAME = "<your username>"
PASSWORD = "<your password>"
CLIENT_ID = "<Longenesis issued client id>"
CLIENT_SECRET = "<Longenesis issued client id>"
ENGAGE_ACTIVITY_SLUG = "<activity SLUG>"
REDIRECT_URL = (
    "https://engage.longenesis.com/partner_view?activitySlug={slug}&code={code}"
)

access_token = requests.post(
    AUTH_ENDPOINT,
    data={
        "username": USERNAME,
        "password": PASSWORD,
        "grant_type": "password",
        "client_id": CLIENT_ID,
        "client_secret": CLIENT_SECRET,
    },
).json()["access_token"]

PERSON_DATA = {
    "participant_id": "0000099",
    "participant_full_name": "John Doe",
    "guardian_id": "0007",
    "guardian_full_name": "Jane Doe",
    "free_text": ["Hello John!"],
}

response = requests.post(
    f"https://engage-openapi.longenesis.com/get_auth_code",
    json=PERSON_DATA,
    headers={"Authorization": f"Bearer {access_token}"},
)

print(
    REDIRECT_URL.format(
        slug=ENGAGE_ACTIVITY_SLUG, code=response.json()["authorization_code"]
    )
)
The documentation on the EngageAPI endpoints is available here here.
Step-by-step review of the python sample

Let's break this example into sections.
First we load the popular requests library.
import requests
Then we sort out the credentials and configuration.
AUTH_ENDPOINT = (
    "https://auth.longenesis.com/realms/curator-engage/protocol/openid-connect/token"
)
USERNAME = "<your username>"
PASSWORD = "<your password>"
CLIENT_ID = "<Longenesis issued client id>"
CLIENT_SECRET = "<Longenesis issued client id>"
ENGAGE_ACTIVITY_SLUG = "<activity SLUG>"
REDIRECT_URL = (
    "https://engage.longenesis.com/partner_view?activitySlug={slug}&code={code}"
)
Next we acquire the access_token for this script.
access_token = requests.post(
    AUTH_ENDPOINT,
    data={
        "username": USERNAME,
        "password": PASSWORD,
        "grant_type": "password",
        "client_id": CLIENT_ID,
        "client_secret": CLIENT_SECRET,
    },
).json()["access_token"]
Then we compile the participant data.
PERSON_DATA = {
    "participant_id": "0000099",
    "participant_full_name": "John Doe"
    "guardian_full_name": "Jane Doe",
    "free_text": ["Hello John!"],
    "org_slug": "sunshinehospital",
}
The required minimal amount of data is just the participant_id i.e. {"participant_id": "aabbcc0011",}.
It is recommended to provide the participant's full name as well: {"participant_id": "aabbcc0011", "participant_full_name": "Janice Doe"}.
In case a parent or guardian is acting on behalf of a minor, the person data information should include the parent's id and name as well.
Please note that the participant_id must be a string with length not greater than 250 characters. The participant_id also must be unique within the Partner's organization.
Next we submit the participant data to EngageAPI.
response = requests.post(
    f"https://engage-openapi.longenesis.com/get_auth_code",
    json=PERSON_DATA,
    headers={"Authorization": f"Bearer {access_token}"},
)
And finally we print the redirect_url on screen.
print(
    REDIRECT_URL.format(
        slug=ENGAGE_ACTIVITY_SLUG, code=response.json()["authorization_code"]
    )
)
A link very similar to this should be next printed on screen: https://engage.longenesis.com/partner_view?activitySlug=abcde&code=A2DA055ED45F4FBE806EAD5B3B937F00
Please note that the print statement in this example is for demo purposes only to have the sample create some output.

The Partner Portal Frontend must implement iFrame similar to what is displayed below where the activitySlug must be set to the slug of your survey that requires registering and the actual authCode must come from the Partner Portal Backend - acquired just before constructing an IFrame.
Below is an example of the iFrame implemented by the Partner Portal Frontend.
<iframe 
  src="https://engage.longenesis.com/partner_view?activitySlug=aabbcc&authCode=AABBCCDDEEFF001122" 
  width="100%" 
  height="1200" 
  style="border:none;"></iframe>
How to invalidate Engage sessions
To invalidate a participant session, Partner Portal must send a POST request to /invalidate/<session_id> endpoint in EngageAPI.
The session_id is included in /get_auth_code response together with the authorization_code. It is up to the Partner how to handle session IDs while the participant is engaged into Engage activities. We recommend for the Partner Portal to store the session ID of the participant in an in-memory database and invalidate the session as soon as the participant navigates away from the page with the EngageUI iFrame.
import requests

AUTH_ENDPOINT = (
    "https://auth.longenesis.com/realms/curator-engage/protocol/openid-connect/token"
)
USERNAME = "<your username>"
PASSWORD = "<your password>"
CLIENT_ID = "<Longenesis issued client id>"
CLIENT_SECRET = "<Longenesis issued client id>"

SESSION_ID = "...load the session_id from the place you stored it..."

access_token = requests.post(
    AUTH_ENDPOINT,
    data={
        "username": USERNAME,
        "password": PASSWORD,
        "grant_type": "password",
        "client_id": CLIENT_ID,
        "client_secret": CLIENT_SECRET,
    },
).json()["access_token"]


response = requests.post(
    f"https://engage-openapi.longenesis.com/invalidate/{SESSION_ID}",
    headers={"Authorization": f"Bearer {access_token}"},
)

print(response.json())
Manage style settings
The Engage integration feature supports various style setting management options. You will be able to adjust the style settings of the integrated Engage content according to the design concept of your portal.

Some examples of tailored style settings can be seen below.
The above examples are an approximate interpretation of the capabilities that the managed style settings feature entails. However, it can be further tailored as per the needs of your project or research initiative.
First and foremost, you will be able to adjust the height, width and position, as well as other parameters of the iFrame element right into your Portal. Whereas, Engage will enable managing the following additional parameters:

1. Primary color: the color of the buttons, highlighted questions, progress bar.
2. Font of the text: It is possible to specify the font, but please note that only those fonts that are free of charge can be applied.
3. The free space around the Engage element or padding: The distance from the Engage element to the borders of the iFrame itself can be defined.
4. The design of the button: width, height, usage of letters for the text (upper/lower case).
5. Design of the iFrame inner rim: rounded edges, border weight. If you wish to have a frame for the Engage content, it would be more convenient to define it right into your Portal, but Engage also allows defining these parameters.
Our team is ready to provide you assistance in any of the steps and would gladly guide you through the process.

Do not hesitate to contact us via support@longenesis.com if you have any questions or any help is required.