Embedding Emakin

With embedded forms, you can easily integrate Emakin forms into other applications using an HTML <iframe>. Emakin’s responsive design ensures that the form automatically adjusts to fit the frame size, providing a smooth and consistent user experience across different devices and screen sizes.

To access embedded forms, you can choose between a valid authentication method or allow anonymous access, depending on your security requirements.

Anonymous Access

Anonymous access allows users to interact with forms or generate reports in other applications without needing to log in to Emakin. This can be achieved by using API Keys, providing a seamless and frictionless experience for users who do not require authentication.

Test Mode

Please note that anonymous access is only available for processes in an "Active" state. If you attempt to use anonymous access while a process is in "Test" mode, Emakin will silently ignore the operation, ensuring that test processes are not unintentionally exposed.

Initiating a New Process Anonymously

To enable anonymous access for initiating a new process, follow these steps:

Enable Anonymous Access: Ensure that anonymous access is enabled for the process you want to initiate or share. This setting allows the process to be accessed without requiring user authentication.
Generate an API Key: Create an API Key with the "login" scope and any other necessary scopes. Be cautious and select only the mandatory scopes, as allowing anonymous access can increase the risk to your system.
Update the Process Link: Copy the initiation link of the process. Replace the # character in the URL with ?, then append the generated API Key as a parameter at the end of the address.

The updated URL should look similar to the following example, with the "apiKey" parameter added:

https://mydomain.emakin.com/app/?/initiate/55....6b/c2...18/08...c8&apiKey=58ea0f3d.....90b984be905a

Sharing a Screen with Anonymous Access

To share a screen view anonymously, follow these steps:

Enable Anonymous Access: First, ensure that anonymous access is enabled for the screen you wish to share. This setting allows users to view the screen without needing to log in.
Generate an API Key: Create an API Key with the "login" scope and any other required scopes. It’s important to only select the necessary scopes, as granting anonymous access can increase the system’s vulnerability.
Update the Screen Link: Copy the screen's URL. Replace the # character in the address with ?, then append the generated API Key as a parameter at the end of the URL.

The updated URL should look similar to the following example, with the "apiKey" parameter included:

https://mydomain.emakin.com/app/?/report/55....c8&apiKey=58ea0f3d.....90b984be905a

Authenticated Access

To secure access, you can generate authentication tokens using the GetToken method from the REST API service for a specific user identity. Once the token is generated, include it as an "auth" parameter in the URL.

Please note that these authentication tokens are valid only for a configured time period and will expire after that. It is essential to generate new tokens whenever needed, and ensure that they are not stored on disk or hardcoded in your application.

The updated URL with the "auth" parameter should look similar to the following example:

https://mydomain.emakin.com/app/?/report/55....c8&auth=41A....114

Embedding a Form

You can easily embed Emakin forms using a basic HTML <iframe> tag, as shown in the example below:

Example:

<html>
<body>
Hello!
<iframe src="https://mydomain.emakin.com/app/?/initiate/55..c8&apiKey=58ea0f3d.....90b984be905a" width="100%" height="300" frameborder="0"></iframe>
</body>
</html>

Return Address

You can specify a returnUrl parameter in the query string to redirect the user to another address after they have completed the form.

Example:

<html>
<body>
Hello!
<iframe src="https://mydomain.emakin.com/app/?/initiate/55..c8&apiKey=58ea0f3d.....90b984be905a&returnUrl=http://localhost" width="100%" height="300" frameborder="0"></iframe>
</body>
</html>

IFrame Size

For some forms, the height of the interface may change dynamically. If you want the IFrame size to adjust automatically according to the form's content, you can use an additional JavaScript library to apply these size changes dynamically.

<html>
<body>
<iframe id="frame" src="https://mydomain.emakin.com/app/?/initiate/55..c8&apiKey=58ea0f3d.....90b984be905a&returnUrl=http://localhost" width="100%" height="300" frameborder="0"></iframe>
<script src="https://static.emakin.com/r/IFrameResizer/JS?c=en-US"></script>
<script>iFrameResize({ minHeight:300 }, '#frame')</script>
</body>

Unlike other examples, make sure to assign an ID to the IFrame element that you want to monitor, as this is essential for tracking and dynamically adjusting its size.

Sending the Culture Parameter

When embedding forms, you may sometimes need them to display in a specific culture or locale, which determines the language, date formats, and other region-specific settings. This can be particularly useful in applications serving a global audience or in situations where the user’s culture is known and you want to provide a seamless experience.

How to Send the Culture Parameter

To specify a culture when embedding a form, you can include the culture parameter in the embedding URL. The culture parameter should be a valid IETF language tag, such as en-US for English (United States) or fr-FR for French (France).

<iframe src="https://mydomain.emakin.com/app/?/initiate/55..c8&apiKey=58ea0f3d.....90b984be905a&culture=en-US" width="100%" height="600px"></iframe>

In this example, the form will be displayed in the English (United States) culture.