Placing the addon settings into Shoptet administration

If your addon includes user settings, you can place the settings page directly in Shoptet administration, as an iframe. The link to addon settings will then be displayed directly in the Shoptet administration menu.

Iframe URL integration

General concept:

• It is important to fill URL for user authorization column in the settings tab, even simple https://your-domain.com is sufficient. Otherwise, we are not able to replace #OAUTH_CODE# with valid value.
• The settings page must be hosted in your environment and run at your URL
• The URL protocol must be https
• Maximum timeout for your page is 60 seconds
• The URL with the settings is entered in the addon’s editor, “Description” tab. The “Link to external addon settings” field may vary for a specific language
• The URL of the link to the external addon settings supports the placeholder #LANGUAGE#, which will be replaced by the actual language of the administration (en, cs, sk, hu)
  
• The page must allow iframe display. This means that the X-Frame-Options header must not be sent within the http response.
• You must authenticate the admin user to avoid someone calls your page for another eshop, we recommend using the OAuth mechanism described here (use the simplified OAuth in this case, point 2.2).

We provide two ways to integrate the page into the iframe:

• directly – the URL is called as you enter it in the addon settings,
• proxy_pass – Shoptet will use an eshop-like URL for the iframe URL (https://sample-eshop/addon/253-cs/your-settings-url), thus pretending the page is local to the eshop, and call your URL on the backend to handle the request.

Direct URL in the iframe

In this case, browsers consider it as third-party page and as such it is less trusted then the parent page(s). In consequence some browsers do not send cookies from other urls and sometimes even between multiple calls of the same page for privacy and security reasons. This means your application must run as cookie-less. Multiple calls of your page must be secured by means of JWT, Paseto or similar.

Proxy pass

Proxy pass is disabled by default. If you want to use proxy pass in your addon, please contact us at api@shoptet.cz.

In case proxy pass is used, sessions are transferred between multiple page calls (with an exception of PHPSESSIONID, which we remove). There are however some limitations to session, asset files and redirects. Generally you need to take into account your script is displayed under different URL than it is called and processed on your server.

Session & cookies
It is important to change your session cookie configuration and set samesite to NONE. This change will fix issue with Chrome browser.

session_set_cookie_params([
    'lifetime' => time() + 60 * 60 * 24,
    'path' => '/',
    'domain' => '',
    'secure' => TRUE,
    'httponly' => TRUE,
    'samesite' => 'NONE',
]);

Assets files
You need to load all your assets, static, files with absolute url. https:// is a matter of course. It is mostly important for css, js and image files.

<!-- Wrong -->
<link type="text/css" rel="stylesheet" href="/static/style.css">
<!-- Right -->
<link type="text/css" rel="stylesheet" href="https://my-shoptet-addon.com/static/style.css">

<!-- Wrong -->
<script src="/static/main.js"></script>
<!-- Right -->
<script src="https://my-shoptet-addon.com/static/main.js"></script>

<!-- Wrong -->
<img src="/img/logo.png" alt="Logo" />
<!-- Right -->
<img src="https://my-shoptet-addon.com/img/logo.png" alt="Logo" />

Redirects
You should not redirect to absolutu url inside your addon. It will cause issue as redirect means “step out” of proxy pass. Because of that “step out” your addon can lost access to cookies and session.

// Wrong
header('Location: https://my-shoptet-addon.com/step2.php');
header('Location: /path/page.php');

// Right
header('Location: step2.php');
header('Location: foo/bar.php');
header('Location: ?page=step2');

Inserting resizing JavaScript into a page

• Add JavaScript to your setting pages to resize the iframe, based on the current page content. You have chosen this solution
• So add to page this javascript code.

Set up page design

• Prepare a page with the addon settings that best respect the design of the shop administration.
• The iframe Demo is prepared for you
• Both CSS styles, and most necessary JavaScripts are available for download.
• JavaScripts contain jQuery, jQuery UI and some basic interactions used in administration – tool tips, tabs and the option to close the message, all indicated in the demo.
• Should you need to use the icon font, you can find it here
• The resizer gets the page height information from the tag <body>. For proper functionality, the CSS style for the <body> tag must not have the height set. The height must change according to the current content of the page.

body {
    height:auto
}

Contents of the page

What the page should contain

• Service name and logo (same as used for Shoptet addons)
• A concise presentation of the service and its benefits – in a maximum of two sentences – in perex at the beginning of the page
• The addon setup section – the goal is to transfer all addon settings directly to the administration of the e-shop without going to third-party pages
• The ability to insert your own widgets, graphs and other elements
• If a user sets up something on the page, adds, selects in select boxes, etc., add the tooltips to each location
• If you mention another part of administration on the page, be sure to include the appropriate link to the page

What the page should not include

The page serves only to set up the addon itself, directly in the administration of the e-shop. Therefore it is prohibited to use it for other purposes. This means:

• Do not present or link any of your other services
• Do not collect any e-shop data via the site which are not needed for the addon to work

Test the page display in administration

• After testing the display, please contact us at api@shoptet.cz. We enable you to see the page in your administration (not visible to other Shoptet clients yet)
• If you have the e-shop addon installed, you will see a link to the addon settings in the administration menu of the addon “Link -> Your addon name” (apart from the exceptions at the top of the list, addons are sorted alphabetically)
• Let us know when you have completed the page. We will review the settings and, once the page is approved, will set it up so that the link to the settings is visible to all users.

TIP: If you want to convert the administration view of an existing addon, it is recommended that you create a test addon with identical settings to test and debug the administration view.