Adding a troubleshooting guide

Migrating the troubleshooting guide from SAAS repo
+ adding a paragraph about issues with embedding iframes related to HTTP headers and cookie parameters.

docs/maps/menu.php

@@ -166,7 +166,8 @@ return [
     ],
     [
         'title' => 'Troubleshooting',
-        'url' => '/map-building/troubleshooting',
+        'url' => '/map-building/troubleshooting.md',
-        'view' => 'content.map.troubleshooting'
+        'markdown' => 'maps.troubleshooting',
+        'editUrl' => 'https://github.com/thecodingmachine/workadventure/edit/develop/docs/maps/troubleshooting.md',
     ],
 ];

docs/maps/opening-a-website.md

@@ -18,11 +18,18 @@ In order to create a zone that opens websites:
 
 {.alert.alert-warning}
 A website can explicitly forbid another website from loading it in an iFrame using
-the [X-Frame-Options HTTP header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options).
+the [X-Frame-Options HTTP header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options). You can
+read more about this common issue and possible workaround the [troubleshooting guide](troubleshooting.md#embedding-an-iframe-is-forbidden).
 
 {.alert.alert-info}
 As an alternative, you may also put the `openWebsite` properties on a layer (rather than putting them on an "area" object)
-but we advise to stick with "area" objects for better performance!
+but we advise sticking with "area" objects for better performance!
+
+{.alert.alert-warning}
+If the website you are embedding is using cookies, those cookies must be configured with the `SameSite=none` attribute. Otherwise,
+they will be ignored by the browser. If you manage to see the website you embed but cannot log into it, the `SameSite` attribute is most
+likely the culprit. You can read more about this common issue and possible workaround the [troubleshooting guide](troubleshooting.md#i-cannot-log-into-my-embedded-website).
+
 
 ## Integrating a Youtube video
 

docs/maps/troubleshooting.md

@@ -0,0 +1,94 @@
+{.section-title.accent.text-primary}
+# Troubleshooting
+
+## Look at the browser console
+
+If your map is not displayed correctly (most notably if you are getting a black screen), open your browser console.
+This is usually done by pressing the F12 key and selecting the "console" tab.
+
+Scan the output. Towards the end, you might see a message explaining why your map cannot be loaded.
+
+## Check webserver CORS settings
+
+If you are hosting the map you built on your own webserver and if the map does not load, please check that 
+[your webserver CORS settings are correctly configured](hosting.md).
+
+## Issues embedding a website
+
+When you are embedding a website in WorkAdventure (whether it is using the [`openWebsite` property](opening-a-website.md) or
+the [integrated website in a map](website-in-map.md) feature or the [Scripting API](scripting.md)), WorkAdventure
+will open your website using an iFrame.
+
+Browsers have various security measures in place, and website owners can use those measures to prevent websites from 
+being used inside iFrames (either partially or completely).
+
+In the chapters below, we will list what can possibly prevent you from embedding a website, and see what are your options.
+
+### Embedding an iFrame is forbidden
+
+The worst that can happen is that the website you are trying to embed completely denies you the authorisation.
+A website owner can do that using the [`X-Frame-Options` HTTP header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options),
+or the newer [`Content-Security-Policy` HTTP header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy).
+
+Take a look at the headers of the page you are trying to load.
+
+{.alert.alert-info}
+You can view the headers of the web page you try to load in the developer tools of your browser (usually accessible using the F12 key
+of your keyboard), in the network tab. Click on the top-most request and check the "Response Headers".
+
+Below is what you can see when opening a Youtube video page:
+
+![](images/x-frame-options.png)
+
+`X-Frame-Options: DENY` or `X-Frame-Options: SAMEORIGIN` will prevent WorkAdventure from loading the page.
+`Content-Security-Policy` header have also the potential to prevent WorkAdventure from loading the page.
+
+If the website you are trying to embed has one of these headers set, here are your options:
+
+- if you have control over the website or know the owner, you can contact the owner/administrator of the website and ask for an exception
+- otherwise, you can look for an "embed" option. Some websites have special pages that can be embedded. For instance,
+  YouTube has special "embed" links that can be used to embed a video in your website. A lot of websites have the same feature (you
+  can usually find those links in the "share" section)
+
+If none of these options are available to you, as a last resort, you can use the [`openTab` property](opening-a-website.md) instead of the `openWebsite` property.
+It will open your webpage in another tab instead of opening it in an iFrame.
+
+### I cannot log into my embedded website
+
+When you log into a website, the website is issuing a "cookie". The cookie is a unique identifier that allows the website
+to recognize you and to identify you. To improve the privacy of their users, browsers can sometimes treat cookies
+inside iFrames as "third-party cookies" and discard them.
+
+Cookies can come with a `SameSite` attribute.
+
+The `SameSite` attribute can take these values: "Lax", "Strict" or "None". The only value that allows using the
+cookie inside an iFrame is "None".
+
+{.alert.alert-info}
+The `SameSite` attribute of your cookie MUST be set to "None" if you want to be able to use this cookie from an iFrame inside WorkAdventure.
+
+**Default values**:
+
+If the "SameSite" attribute is not explicitly set, [the behaviour depends on the browser](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite#browser_compatibility).
+Chrome, Edge and Opera will default to "Lax".
+Firefox and Safari will default to "None" (as of 2022/04/25).
+
+As a result, a website that does not set the `SameSite` attribute on cookies will work correctly in Firefox and Safari but 
+login will fail on Chrome, Edge and Opera.
+
+If the website you are trying to embed has the `SameSite` attribute set to a value other than "None", here are your options:
+
+- if you have control over the website or know the owner, you can contact the owner/administrator of the website and ask
+  the owner/administrator to change the `SameSite` settings.
+- otherwise, you will have to use the [`openTab` property](opening-a-website.md) instead of the `openWebsite` property.
+  It will open your webpage in another tab instead of in an iFrame.
+
+## Need some help?
+
+<div class="card bg-red text-white"><div class="card-body">
+        <p>WorkAdventure is a constantly evolving project and there is plenty of room for improvement regarding map editing.</p>
+        <p>If you are facing any troubles, do not hesitate to seek help in 
+            <a href="https://discord.gg/G6Xh9ZM9aR">our Discord server</a> or open an "issue" in the
+            <a href="https://github.com/thecodingmachine/workadventure/issues" target="_blank">GitHub WorkAdventure account</a>.
+        </p>
+</div></div>