diff --git a/docs/Client/01-intro.md b/docs/Client/01-intro.md
index 72b47a2..88f07ae 100644
--- a/docs/Client/01-intro.md
+++ b/docs/Client/01-intro.md
@@ -5,158 +5,17 @@ sidebar_position: 1
---
# TrustedLogin SDK
+
Easily and securely log in to your customers sites when providing support.
## Our priority: Be secure and [don't crash sites](https://www.bugsnag.com/blog/sdks-should-not-crash-apps) {#our-priority-sdks-should-not-crash-sites}
When you integrate TrustedLogin into your project (theme, plugin, or custom code), you are counting on us not to mess up your customer or clients' sites. We take that extremely seriously.
--------
-
-## Including in your plugin or theme {#including-in-your-plugin-or-theme}
-
-:::info
-### When you see `ProBlockBuilder`, make sure to replace with your own namespace!
-In the examples below, we're going to pretend your plugin or theme is named "Pro Block Builder" and your business is named Widgets, Co. These should not be the names you use—make sure to update the sample code below to match your business and plugin/theme name!
-:::
-
-### Install Strauss & update your composer.json file
-
-1. [Install Strauss](https://github.com/BrianHenryIE/strauss#use). Strauss is used for namespacing the Client to prevent conflicts with other plugins or themes that are using TrustedLogin. We recommend installing via the `strauss.phar` method.
- 1. `cd` into your plugin or theme directory
- 1. Run `curl -o strauss.phar -L -C - https://github.com/BrianHenryIE/strauss/releases/latest/download/strauss.phar`
-1. Run `composer require trustedlogin/client:dev-main` to install the TrustedLogin Client SDK
-1. Run `composer require scssphp/scssphp --dev` to install `scssphp` as a dev dependency. This is used to generate and namespace the CSS used by TrustedLogin. If you already have `scssphp` installed, or are [using an alternative way to namespace the CSS](/Client/css-namespacing.md), skip this step.
-1. Update your `composer.json` file to integrate with Strauss. Follow the instructions as detailed in the [Strauss documentation](https://github.com/BrianHenryIE/strauss#configuration) for namespacing your plugin and theme. See example below.
-
-```json
-[...]
- "require": {
- "trustedlogin/client": "dev-main"
- },
- "require-dev": {
- "brianhenryie/strauss": "dev-master",
- "scssphp/scssphp": "^v1.11.0"
- },
- "autoload": {
- "classmap": [
- "vendor"
- ]
- },
- "extra": {
- "strauss": {
- "target_directory": "vendor-namespaced",
- "namespace_prefix": "ProBlockBuilder\\",
- "classmap_prefix": "ProBlockBuilder_",
- "classmap_output": true,
- "packages": [
- "trustedlogin/client"
- ]
- }
- },
- "scripts": {
- "strauss": [
- "@php strauss.phar"
- ],
- "trustedlogin": [
- "@php vendor/bin/build-sass --namespace=ProBlockBuilder"
- ],
- "post-install-cmd": [
- "@strauss",
- "@trustedlogin"
- ],
- "post-update-cmd": [
- "@strauss",
- "@trustedlogin"
- ]
- }
-[...]
-```
-4. Run `composer update` to update your dependencies. Strauss should generate a `vendor-namespaced/` directory. If it doesn't, you may need to run `composer install` first.
-5. Follow [these directions to configure and instantiate the client](./configuration)
-
-#### To manually include the autoloader
-
-If you chose to set `classmap_output` to `false` in the Strauss configuration, you will need to include the autoloader in your code. If using the sample above, it would be located at `vendor-namepaced/autoload.php`; the code would be something like:
-
-```php
-// For a plugin or theme:
-include_once trailingslashit( dirname( __FILE__ ) ) . 'vendor-namespaced/autoload.php';
-```
-
-#### Vendor directory cleanup
-
-If you find the TrustedLogin directories in your `vendor/` directory to be undesirable for some reason, you may use this configuration for the `trustedlogin` script in Composer.
-
-Replace this:
-
-```json
-"trustedlogin": [
- "@php vendor/bin/build-sass --namespace=ProBlockBuilder"
- ],
-```
-
-With this:
-
-```json
-"trustedlogin": [
- "@php vendor/bin/build-sass --namespace=ProBlockBuilder",
- "[ -d 'vendor/trustedlogin' ] && rm -rf vendor/trustedlogin || true",
- "[ -d 'vendor/scssphp' ] && rm -rf vendor/scssphp || true",
- "[ -d 'vendor/bin' ] && rm -rf vendor/bin/build-sass && rm -rf vendor/bin/pscss || true"
- ],
-```
-
-The script modification will now remove the `trustedlogin`, `scssphp`, and TrustedLogin-related files inside `bin`.
-
-### No-Conflict mode {#no-conflict-mode}
-
-Some plugins like Gravity Forms and GravityView have a "no-conflict mode" to limit script and style conflicts. If you see
-scripts and styles not loading on your Grant Support Access page, that's what's going on.
-
-The WordPress script and style handles registered by TrustedLogin are formatted as `trustedlogin-{namespace}`.
-Here's an example of how GravityView (with a namespace of `gravityview`) allows TrustedLogin scripts:
-
-```php
-add_filter( 'gravityview_noconflict_scripts', function ( $allowed_scripts = array() ) {
-
- $allowed_scripts[] = 'trustedlogin-gravityview'; // ⚠️ GravityView's namespace is `gravityview`
-
- return $allowed_scripts;
-} );
-```
-
-### Testing on local environments {#testing-on-local-environments}
-
-TrustedLogin won't work in local environments unless using a tunnel such as ngrok. Thus, TrustedLogin will display a warning when attempting to generate a login when in a local environment.
-
-To disable the warning, define `TRUSTEDLOGIN_DISABLE_LOCAL_NOTICE` and set it to true:
-
-```php
-define( 'TRUSTEDLOGIN_DISABLE_LOCAL_NOTICE', true );
-```
-
-## Reference IDs {#reference-ids}
-
-Reference IDs are useful when you want to attach a specific ticket ID or conversation ID to a login.
-
-Reference IDs can be passed via URL like so: `wp-login.php?action=trustedlogin&ns={namespace}&ref=[123]`
-
-When a Reference ID exists, users will see the reference while granting access:
-
-
-
-## Logging {#logging}
-
-We recommend disabling logging by default, but sometimes logs are necessary.
+## What is TrustedLogin?
-1. TrustedLogin creates a `trustedlogin-logs` directory inside the `wp-content/uploads/` directory.
-2. An empty `index.html` file is placed inside the directory to prevent browsing.
-3. New log files are created daily for each TrustedLogin namespace. The default log `filename` format is `client-{namespace}-{Y-m-d}-{hash}.log`
- - `{namespace}` is the namespace of your business, plugin, or theme name
- - `{date}` is `YYYY-MM-DD` format
- - The hash is generated using `wp_hash()` using on the `vendor/namespace`, site `home_url()`, and the day of the year (`date('z')`). The point of the hash is to make log names harder to guess (security by obscurity).
+TrustedLogin is a secure and easy-to-use SDK that allows you to log in to your customers' WordPress sites without them sharing passwords. It is designed to be easy to integrate into your plugin, theme, or custom code.
-### Using your own logging library {#using-your-own-logging-library}
+## Why use TrustedLogin?
-If you add an action for `trustedlogin/{namespace}/logging/log`, TrustedLogin will let you handle logging. The `trustedlogin-logs` directory and log files will not be created.
+Customer support is a critical part of any business. TrustedLogin makes it easy to provide support to your customers without the need for them to share their passwords. This is a huge win for both you and your customers.
diff --git a/docs/Client/02-installation.md b/docs/Client/02-installation.md
new file mode 100644
index 0000000..ba40468
--- /dev/null
+++ b/docs/Client/02-installation.md
@@ -0,0 +1,155 @@
+---
+title: Installation
+sidebar: auto
+sidebar_position: 2
+---
+
+## Including in your plugin or theme {#including-in-your-plugin-or-theme}
+
+### 1. Install the TrustedLogin SDK using Composer
+
+Run `composer require trustedlogin/client:dev-main` to install the TrustedLogin Client SDK as a dependency.
+
+### 2. Add SCSS as a dev dependency
+
+Run `composer require scssphp/scssphp --dev` to install `scssphp` as a dev dependency.
+
+This is used to generate and namespace the CSS used by TrustedLogin. If you already have `scssphp` installed, or are [using an alternative way to namespace the CSS](/Client/css-namespacing.md), skip this step.
+
+### 3. Namespace the SDK using [Strauss](/Client/namespacing/strauss) or [PHP-Scoper](/Client/namespacing/php-scoper).
+
+In order to prevent conflicts with other plugins or themes that are using TrustedLogin, you must namespace the TrustedLogin Client SDK.
+
+We support two namespacing tools: Strauss and PHP-Scoper. Choose the one that best fits your needs:
+
+- [Strauss](/Client/namespacing/strauss)
+- [PHP-Scoper](/Client/namespacing/php-scoper)
+
+### 4. [Namespace the CSS files](/Client/Namespacing/css-namespacing)
+
+TrustedLogin CSS files are namespaced so that they don't conflict with other plugins or themes that are using TrustedLogin.
+
+Follow the [CSS Namespacing](/Client/css-namespacing.md) guide.
+
+### 4. Include the autoloader
+
+Make sure you have the Composer autoloader included in your plugin or theme. If you already have the autoloader included, you can skip this step.
+
+```php
+// Include the Composer autoloader.
+require_once trailingslashit( dirname( __FILE__ ) ) . 'vendor/autoload.php';
+```
+
+Make sure to **include the autoloader on all page loads** to ensure the TrustedLogin SDK is available when needed.
+
+### 5. Customize the [TrustedLogin configuration](/Client/configuration) options
+
+The configuration array is where you set up the TrustedLogin Client SDK to work with your plugin or theme. You can customize the configuration to match your needs.
+
+### 6. Instantiate the TrustedLogin Client
+
+:::info
+The TrustedLogin client must be initialized on all page loads, both the front-end and the dashboard.
+:::
+
+When instantiating the TrustedLogin `Client` class, you need to pass a valid `Config` object.
+
+The following is a minimal configuration. It has all the _required_ settings, but not all **recommended** settings!
+
+```php
+/**
+ * This is a basic example of how to instantiate the TrustedLogin Client, using the minimum required configuration
+ * settings and hooked into the `plugins_loaded` action. Adjust the configuration to match your needs.
+ */
+add_action( 'plugins_loaded', function() {
+ $config = [
+ 'auth' => [
+ 'api_key' => '1234567890',
+ ],
+ 'vendor' => [
+ 'namespace' => 'pro-block-builder',
+ 'title' => 'Pro Block Builder',
+ 'email' => 'support@example.com',
+ 'website' => 'https://example.com',
+ 'support_url' => 'https://help.example.com',
+ ],
+ 'role' => 'editor',
+ ];
+
+ try {
+ new \ProBlockBuilder\TrustedLogin\Client(
+ new \ProBlockBuilder\TrustedLogin\Config( $config )
+ );
+ } catch ( \Exception $exception ) {
+ error_log( $exception->getMessage() );
+ }
+} );
+```
+
+#### Hooking the TrustedLogin Client instantiation
+
+We recommend instantiating the TrustedLogin Client on the `plugins_loaded` action. This ensures that the TrustedLogin Client is available on all page loads.
+
+TrustedLogin calls the following hooks:
+- `init` priority `100`
+- `admin_init` priority `100`
+- `template_redirect` priority `99`
+
+Instantiating the Client after any of these hooks are called will cause TrustedLogin to not function properly.
+
+:::warning
+**Always wrap TrustedLogin Client instantiation in a try/catch block!**
+:::
+
+TrustedLogin Client instantiation must be wrapped in a try/catch block. The TrustedLogin Client throws Exceptions when:
+
+- The configuration is invalid.
+- TrustedLogin is globally disabled.
+- TrustedLogin is disabled for the namespace.
+- The current website lacks expected encryption functions (these _should_ be included in all WordPress installations as well as PHP 7.2).
+
+Wrapping the instantiation in a try/catch block ensures that the site won't crash if TrustedLogin fails to initialize.
+
+------
+
+## Advanced
+
+### Vendor directory cleanup
+
+If you find the TrustedLogin directories in your `vendor/` directory to be undesirable for some reason, you may use this configuration for the `trustedlogin` script in Composer.
+
+:::info
+### When you see `ProBlockBuilder`, make sure to replace with your own namespace!
+In the examples below, we're going to pretend your plugin or theme is named "Pro Block Builder" and your business is named Widgets, Co. These should not be the names you use—make sure to update the sample code below to match your business and plugin/theme name!
+:::
+
+Replace this:
+
+```json
+"trustedlogin": [
+ "@php vendor/bin/build-sass --namespace=ProBlockBuilder"
+ ],
+```
+
+With this:
+
+```json
+"trustedlogin": [
+ "@php vendor/bin/build-sass --namespace=ProBlockBuilder",
+ "[ -d 'vendor/trustedlogin' ] && rm -rf vendor/trustedlogin || true",
+ "[ -d 'vendor/scssphp' ] && rm -rf vendor/scssphp || true",
+ "[ -d 'vendor/bin' ] && rm -rf vendor/bin/build-sass && rm -rf vendor/bin/pscss || true"
+ ],
+```
+
+The script modification will now remove the `trustedlogin`, `scssphp`, and TrustedLogin-related files inside `bin`.
+
+### Testing on local environments {#testing-on-local-environments}
+
+TrustedLogin won't work in local environments unless using a tunnel such as ngrok. Thus, TrustedLogin will display a warning when attempting to generate a login when in a local environment.
+
+To disable the warning, define `TRUSTEDLOGIN_DISABLE_LOCAL_NOTICE` and set it to true:
+
+```php
+define( 'TRUSTEDLOGIN_DISABLE_LOCAL_NOTICE', true );
+```
diff --git a/docs/Client/configuration.md b/docs/Client/configuration.md
index 6ed3608..07559eb 100644
--- a/docs/Client/configuration.md
+++ b/docs/Client/configuration.md
@@ -1,3 +1,9 @@
+---
+title: Configuring the TrustedLogin Client SDK
+sidebar_label: Client Configuration
+sidebar_position: 5
+---
+
# Client Configuration
## Minimal configuration {#minimal-configuration}
@@ -6,16 +12,7 @@ When instantiating the TrustedLogin `Client` class, you need to pass a valid `Co
The following is a minimal configuration. It has all the _required_ settings, but not all **recommended** settings!
-:::info
-### When you see `ProBlockBuilder`, make sure to replace with your own namespace! {#when-you-see-problockbuilder-make-sure-to-replace-with-your-own-namespace}
-In the examples below, we're going to pretend your plugin or theme is named "Pro Block Builder" and your business is named Widgets, Co. These should not be the names you use—make sure to update the sample code below to match your business and plugin/theme name!
-:::
-
```php
-
-// Include the Composer autoloader.
-include_once trailingslashit( dirname( __FILE__ ) ) . 'vendor/autoload.php';
-
$config = [
'auth' => [
'api_key' => '1234567890',
@@ -29,35 +26,57 @@ $config = [
],
'role' => 'editor',
];
-
-try {
- new \ProBlockBuilder\TrustedLogin\Client(
- new \ProBlockBuilder\TrustedLogin\Config( $config )
- );
-} catch ( \Exception $exception ) {
- error_log( $exception->getMessage() );
-}
```
-:::warning
-Make sure initialization happens before headers are sent. `init` is a good hook to use.
-
-**The hook must run on the front-end!** For example, don't use `admin_init`, since it will not run on the front-end.
+:::note
+### When you see `ProBlockBuilder`, this is a placeholder. Make sure to replace with your own namespace! {#when-you-see-problockbuilder-make-sure-to-replace-with-your-own-namespace}
+In the examples on this page, we're going to pretend your plugin or theme is named "Pro Block Builder" and your business is named Widgets, Co. These should not be the names you use—make sure to update the sample code below to match your business and plugin/theme name!
:::
+## A more complete configuration {#a-more-complete-configuration}
+
+The following is a more complete configuration. It includes all the settings that can be configured.
+
+```php
+$config = [
+ 'auth' => [
+ 'api_key' => '12345678',
+ ],
+ 'vendor' => [
+ 'namespace' => 'pro-block-builder',
+ 'title' => 'Pro Block Builder',
+ 'email' => 'support@example.com',
+ 'website' => 'https://example.com',
+ 'support_url' => 'https://help.example.com',
+ 'logo_url' => plugins_url( 'path/to/logo/image/logo.svg', EXAMPLE_PBB_PLUGIN_FILE_PATH ),
+ ],
+ 'role' => 'editor',
+ 'clone_role' => false,
+ 'menu' => [
+ 'slug' => 'example', // This is the `page` attribute of top-level menu item (eg: `admin.php?page=example`).
+ 'title' => esc_html__( 'Grant Site Access', 'pro-block-builder' ),
+ ],
+ 'webhook' => [
+ 'url' => 'https://hooks.zapier.com/hooks/catch/12345/example/silent/', // Zapier webhook URL.
+ 'debug_data' => true,
+ 'create_ticket' => true,
+ ],
+];
+```
+
## All configuration options {#all-options}
| Key | Type | Description | Default | Required? |
|-------------------------|-------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|:---------:|
-| `auth/api_key` | `string` | The TrustedLogin key for the vendor, found in "API Keys" on https://app.trustedlogin.com. | `null` | ✅ |
+| `auth/api_key` | `string` | The TrustedLogin key for the vendor, found in "API Keys" on https://app.trustedlogin.com. | `null` | ✅ |
| `auth/license_key` | `string`, `null` | If enabled, the license key for the current client. This is used as a lookup value when integrating with help desk support widgets. If not defined, a cryptographic hash will be generated to use as the Access Key. | `null` | |
-| `role` | `string` | The role to clone when creating a new Support User. | `editor` | ✅ |
+| `role` | `string` | The role to clone when creating a new Support User. | `editor` | ✅ |
| `clone_role` | `bool` | If true, create a new role with the same capabilites as the `role` setting. If false, use the defined `role` setting. | `true` | |
-| `vendor/namespace` | `string` | Slug for vendor. Must be unique. Must be shorter than 96 characters. Must not be a reserved namespace: `trustedlogin`, `client`, `vendor`, `admin`, `wordpress` | `null` | ✅ |
-| `vendor/title` | `string` | Name of the vendor company. Used in text such as `Visit the %s website` | `null` | ✅ |
-| `vendor/email` | `string` | Email address for support. Used when creating usernames. Recommended: use `{hash}` dynamic replacement ([see below](#email-hash)). | `null` | ✅ |
-| `vendor/website` | `string` | URL to the vendor website. Must be a valid URL. | `null` | ✅ |
-| `vendor/support_url` | `string` | URL to the vendor support page. Shown to users in the Grant Access form and also serves as a backup to redirect users if the TrustedLogin server is unreachable. Must be a valid URL. | `null` | ✅ |
+| `vendor/namespace` | `string` | Slug for vendor. Must be unique. Must be shorter than 96 characters. Cannot be a reserved namespace. ([learn more about the vendor namespace setting below](#vendor-namespace)) | `null` | ✅ |
+| `vendor/title` | `string` | Name of the vendor company. Used in text such as `Visit the %s website` | `null` | ✅ |
+| `vendor/email` | `string` | Email address for support. Used when creating usernames. Recommended: use `{hash}` dynamic replacement ([see below](#email-hash)). | `null` | ✅ |
+| `vendor/website` | `string` | URL to the vendor website. Must be a valid URL. | `null` | ✅ |
+| `vendor/support_url` | `string` | URL to the vendor support page. Shown to users in the Grant Access form and also serves as a backup to redirect users if the TrustedLogin server is unreachable. Must be a valid URL. | `null` | ✅ |
| `vendor/display_name` | `string` | Optional. Display name for the support team. See "Display Name vs Title" below. | `null` | |
| `vendor/logo_url` | `string` | Optional. URL to the vendor logo. Displayed in the Grant Access form. May be inline SVG. Must be local to comply with WordPress.org. | `null` | |
| `caps/add` | `array` | An array of additional capabilities to be granted to the Support User after their user role is cloned based on the `role` setting.
The key is the capability slug and the value is the reason why it is needed. Example: `[ 'gf_full_access' => 'Support will need to see and edit the forms, entries, and Gravity Forms settings on your site.' ]` | `[]` | |
@@ -67,8 +86,8 @@ Make sure initialization happens before headers are sent. `init` is a good hook
| `menu/title` | `string` | The title of the submenu in the sidebar menu. | `Grant Support Access` | |
| `menu/icon_url` | `string` | The URL to the icon to be used for this menu. The value is passed as `$icon_url` to the [`add_menu_page()` function](https://developer.wordpress.org/reference/functions/add_menu_page/). | `''` (empty string) | |
| `menu/priority` | `int` | The priority of the `admin_menu` action used by TrustedLogin. | `100` | |
-| `menu/position` | `int` | The `$position` argument passed to the [`add_submenu_page()` function](https://developer.wordpress.org/reference/functions/add_submenu_page/) function. | `null` | |
-| `logging/enabled` | `bool` | If enabled, logs are stored in `wp-content/uploads/trustedlogin-logs` | `false` | |
+| `menu/position` | `int`, `float`, `null` | The `$position` argument passed to the [`add_submenu_page()` function](https://developer.wordpress.org/reference/functions/add_submenu_page/) function. | `null` | |
+| `logging/enabled` | `bool` | If enabled, logs are stored in `wp-content/uploads/trustedlogin-logs` | `false` | |
| `logging/directory` | `null`,`string` | Override the directory where logs are stored. See [Logging](logging/) for more information. | `null` | |
| `logging/threshold` | `string` | Define what [PSR log level](https://www.php-fig.org/psr/psr-3/#5-psrlogloglevel) should be logged. To log everything, set the threshold to `debug`. | `notice` | |
| `logging/options` | `array` | Array of [KLogger Additional Options](https://github.com/katzgrau/klogger#additional-options) | `['extension' => 'log', 'dateFormat' => 'Y-m-d G:i:s.u', 'filename' => null, 'flushFrequency' => false, 'logFormat' => false, 'appendContext' => true ]` | |
@@ -84,14 +103,29 @@ Make sure initialization happens before headers are sent. `init` is a good hook
## Logging {#logging}
+**We recommend disabling logging.**
+
+When logging is enabled, TrustedLogin logs to the `wp-content/uploads/trustedlogin-logs/` directory by default.
+
+1. TrustedLogin creates a `trustedlogin-logs` directory inside the `wp-content/uploads/` directory.
+2. An empty `index.html` file is placed inside the directory to prevent browsing.
+3. New log files are created daily for each TrustedLogin namespace. The default log `filename` format is `client-debug-{Y-m-d}-{hash}.log`
+ - `{namespace}` is the namespace of your business, plugin, or theme name
+ - `{date}` is `YYYY-MM-DD` format
+ - The hash is generated using `wp_hash()` using on the `vendor/namespace`, site `home_url()`, and the day of the year (`date('z')`). The point of the hash is to make log names harder to guess (security by obscurity).
+
+### Using your own logging library {#using-your-own-logging-library}
+
+If you add an action for `trustedlogin/{namespace}/logging/log`, TrustedLogin will let you handle logging. The `trustedlogin-logs` directory and log files will not be created.
+
### Default settings: {#default-settings}
```php
-'logging' => array(
+'logging' => [
'enabled' => false,
'directory' => null,
'threshold' => 'debug',
- 'options' => array(),
-),
+ 'options' => [],
+],
```
### logging/enabled {#loggingenabled}
@@ -103,17 +137,17 @@ Whether to enable logging TrustedLogin activity to a file. Helpful for debugging
To enable logging in TrustedLogin, the minimum configuration necessary is:
```php
-'logging' => array(
+'logging' => [
'enabled' => true,
-),
+],
```
### `logging/directory` {#loggingdirectory}
_Optional._ Default: `null`
-If `null`, TrustedLogin will generate its own directory inside the `wp-uploads/` directory. The path for logs is
-`/wp-uploads/trustedlogin-logs/`. Created directories are protected by an index.html file to prevent browsing.
+If `null`, TrustedLogin will generate its own directory inside the `wp-content/uploads/` directory. The path for logs is
+`/wp-content/uploads/trustedlogin-logs/`. Created directories are protected by an `index.html` file to prevent browsing.
### `logging/threshold` {#loggingthreshold}
@@ -152,6 +186,33 @@ There is one log file generated per day. Log file names use a hash to make them
Example: `trustedlogin-debug-2020-07-27-39dabe12636f200938bbe8790c0aef94.log`
+## Vendor namespaces {#vendor-namespace}
+
+Namespaces are used to isolate your TrustedLogin configuration from other plugins or themes that may also use TrustedLogin. They must be unique.
+
+Some of the places the namespace is used include:
+
+- The default dashboard URL for the Grant Access page: `/wp-admin/admin.php?page=grant-{namespace}-access`
+- The WP Login Grant access URL: `wp-login.php?action=trustedlogin&ns={namespace}`
+- The user role created for support access: `{namespace}-support`
+- The CSS classes used in the Grant Access form
+- Actions and filters (eg: `trustedlogin/{namespace}/access/created`)
+- The name of the constant to disable TrustedLogin (eg: `TRUSTEDLOGIN_DISABLE_{NAMESPACE}`)
+- As part of a hash for the log file name
+
+### Reserved namespaces {#reserved-namespaces}
+
+The following namespaces are reserved and cannot be used:
+
+- `trustedlogin`
+- `trusted-login`
+- `client`
+- `vendor`
+- `admin`
+- `administrator`
+- `wordpress`
+- `support`
+
## Display Name vs Title {#display-name-vs-title}
If `vendor/title` is set to `GravityView`, the default confirmation screen will say `Grant GravityView access to your site.`
diff --git a/docs/Client/customization.md b/docs/Client/customization.md
index d406d11..957f4d5 100644
--- a/docs/Client/customization.md
+++ b/docs/Client/customization.md
@@ -1,6 +1,6 @@
---
title: Template Customization
-sidebar: auto
+sidebar: none
---
# Customizing the TrustedLogin Template
diff --git a/docs/Client/hooks.md b/docs/Client/hooks.md
index c0f77ce..ac22a17 100644
--- a/docs/Client/hooks.md
+++ b/docs/Client/hooks.md
@@ -1,5 +1,7 @@
# Hooks
+Below are all hooks available in the TrustedLogin Client. These hooks can be used to customize the behavior of the Client.
+
## Actions {#actions}
### `trustedlogin/{namespace}/auth_screen` {#trustedloginnamespaceauthscreen}
diff --git a/docs/Client/css-namespacing.md b/docs/Client/namespacing/css-namespacing.md
similarity index 87%
rename from docs/Client/css-namespacing.md
rename to docs/Client/namespacing/css-namespacing.md
index c59a119..8b2c323 100644
--- a/docs/Client/css-namespacing.md
+++ b/docs/Client/namespacing/css-namespacing.md
@@ -1,6 +1,7 @@
---
title: CSS Namespacing
sidebar: auto
+sidebar_position: 3
---
# Namespacing CSS Files
@@ -9,9 +10,8 @@ TrustedLogin CSS files are namespaced so that they don't conflict with other plu
The `build-sass` script accepts the following arguments:
- `--namespace`: The namespace to use for the CSS files. This is required.
-- `--path`: The path to the TrustedLogin client directory. This is optional, and defaults to `vendor/trustedlogin/client/src/assets/`.
-- `--export_dir`: The path to the output directory. This is optional, and defaults to `vendor/trustedlogin/client/src/assets/`.
-- `--relative_images_dir`: The path to the images directory, relative to the output directory. This is optional, and defaults to `./`.
+- `--assets_dir`: The path to the TrustedLogin client directory. This is optional, and defaults to `(vendor-namespaced|vendor-prefixed)/trustedlogin/client/src/assets/`.
+- `--export_dir`: The path to the output directory. This is optional, and defaults to `(vendor-namespaced|vendor-prefixed)/trustedlogin/client/src/assets/`.
The default way to namespace files is [as a Composer script](/Client/01-intro.md), but this may not work with your build process: the default implementation shown adds the required SCSS package (`scssphp/scssphp`) to the `require-dev` array, which may not work with your release flow. If you move `scssphp/scssphp` to the `require` array, the scssphp library will be included in your autoloader, which adds bloat for something that should be used one-time.
@@ -45,7 +45,6 @@ If you'd like to use an SCSS mixin to namespace CSS files, you can use the follo
@import "vendor-namespaced/trustedlogin/client/src/assets/src/global";
$namespace: "ProBlockBuilder";
-$path: "example/different/assets/path/"; // Path to assets directory (for loading and lock images)
@include trustedlogin-auth( $namespace );
@include trustedlogin-button( $namespace );
diff --git a/docs/Client/namespacing/index.md b/docs/Client/namespacing/index.md
new file mode 100644
index 0000000..40bb509
--- /dev/null
+++ b/docs/Client/namespacing/index.md
@@ -0,0 +1,18 @@
+---
+title: Namespacing
+sidebar: auto
+sidebar_position: 3
+---
+
+Namespacing is vital for any instance of TrustedLogin to not conflict with other code running TrustedLogin.
+
+There are two parts of the code that must be namespaced for TrustedLogin to function properly:
+
+## PHP
+
+- [Strauss](/Client/namespacing/strauss)
+- [PHP-Scoper](/Client/namespacing/php-scoper)
+
+## CSS
+
+- [CSS Namespacing](/Client/namespacing/css-namespacing)
diff --git a/docs/Client/namespacing/php-scoper.md b/docs/Client/namespacing/php-scoper.md
new file mode 100644
index 0000000..84f436b
--- /dev/null
+++ b/docs/Client/namespacing/php-scoper.md
@@ -0,0 +1,181 @@
+---
+title: Namespacing with PHP-Scoper
+sidebar_label: PHP-Scoper
+sidebar: auto
+sidebar_position: 2
+---
+
+## Using PHP-Scoper
+
+PHP-Scoper may be used for namespacing the TrustedLogin client to prevent conflicts with other plugins or themes that are using TrustedLogin.
+
+### 1. Install PHP-Scoper
+
+Follow the instructions in the [PHP-Scoper documentation](https://github.com/humbug/php-scoper/blob/main/docs/installation.md#installation) to install PHP-Scoper.
+
+### 2. Install the TrustedLogin Client SDK
+
+1. Run `composer require trustedlogin/client:dev-main` to install the TrustedLogin Client SDK
+1. Run `composer require scssphp/scssphp --dev` to install `scssphp` as a dev dependency. This is used to generate and namespace the CSS used by TrustedLogin. If you already have `scssphp` installed, or are [using an alternative way to namespace the CSS](/Client/css-namespacing.md), skip this step.
+
+## Create or modify the PHP-Scoper Configuration
+
+When using PHP-Scoper to prefix the TrustedLogin client, you will need to update the configuration to include additional files or classes that should not be prefixed.
+
+To update the PHP-Scoper configuration, you create a `scoper.inc.php` file in the root of your project. This file should return an array with the configuration options for PHP-Scoper.
+
+Here is an example of a PHP-Scoper configuration file that includes additional files and classes that should not be prefixed in TrustedLogin:
+
+```php
+ [
+ Finder::create()->files()->in( 'vendor/trustedlogin/client' )->name( [
+ 'LICENSE',
+ 'composer.json'
+ ] ),
+ Finder::create()->files()->in( 'vendor/trustedlogin/client/src' )->name( [
+ '*.php',
+ '*.css',
+ '*.js',
+ ] ),
+ ],
+
+ /*
+ * When scoping PHP files, there will be scenarios where some of the code being scoped indirectly references the
+ * original namespace. These will include, for example, strings or string manipulations. PHP-Scoper has limited
+ * support for prefixing such strings. To circumvent that, you can define patchers to manipulate the file to your
+ * heart contents.
+ *
+ * For more see: https://github.com/humbug/php-scoper#patchers
+ */
+ 'patchers' => [
+ /**
+ * Replaces the Adapter prefixed versions with the original ones.
+ *
+ * @param string $filePath The path of the current file.
+ * @param string $prefix The prefix to be used.
+ * @param string $content The content of the specific file.
+ *
+ * @return string The modified content.
+ */
+ function( $file_path, $prefix, $content ) {
+
+ // This is a list of classes and functions that TrustedLogin uses that should not be prefixed.
+ $trustedlogin_allowlist = [
+ 'DateTime',
+ 'Exception',
+ 'ImagickException',
+ 'RuntimeException',
+ 'WP_Admin_Bar',
+ 'WP_Debug_Data',
+ 'WP_Error',
+ 'WP_Filesystem_Base',
+ 'WP_Filesystem',
+ 'wp_get_environment_type',
+ 'WP_User',
+ ];
+
+ foreach ( $trustedlogin_allowlist as $class ) {
+ $content = str_replace( [
+ $prefix . '\\' . $class, // Adapter-prefixed.
+ $prefix . '\\\\' . $class // Catch double-escaped classes.
+ ], $class, $content );
+ }
+
+ return $content;
+ },
+ ],
+];
+```
+
+## 3. Run PHP-Scoper
+
+After you have created or updated the PHP-Scoper configuration, you can run PHP-Scoper to prefix the TrustedLogin client. Run the following command:
+
+:::info
+### When you see `ProBlockBuilder`, make sure to replace with your own namespace! {#when-you-see-problockbuilder-make-sure-to-replace-with-your-own-namespace}
+In the examples below, we're going to pretend your plugin or theme is named "Pro Block Builder" and your business is named Widgets, Co. These should not be the names you use—make sure to update the sample code below to match your business and plugin/theme name!
+:::
+
+### Using the PHP-Scoper Phar
+
+```bash
+php php-scoper.phar add-prefix --prefix=ProBlockBuilder
+```
+
+### Using the PHP-Scoper Composer Package
+
+```bash
+composer php-scoper add-prefix --prefix=ProBlockBuilder
+```
+
+### Using phive-installed PHP-Scoper
+
+```bash
+tools/php-scoper add-prefix --prefix="ProBlockBuilder"
+```
+
+PHP-Scoper will prefix the TrustedLogin client files and generate a `build/` directory.
+
+## 4. Update the Composer Autoloader
+
+After PHP-Scoper has prefixed the TrustedLogin client files, you will need to update the Composer autoloader to include the new `build/` directory. To do this, add the following to your `composer.json` file:
+
+```json
+"autoload": {
+ "classmap": [
+ "vendor",
+ "build"
+ ]
+}
+```
+
+After updating the Composer autoloader, run `composer dump-autoload` to update the autoloader.
+
+### 5. Include the autoloader
+
+When using Composer, you likely already have added an autoloader to your code, using something like `require_once 'vendor/autoload.php';`.
+
+If your PHP-Scoper build isn't picked up by the autoloader, you may need to include the autoloader in your code.
+
+```php
+// For a plugin or theme:
+include_once trailingslashit( dirname( __FILE__ ) ) . 'build/autoload.php';
+```
+
+## 6. Add a Composer Script
+
+You can also add a Composer script to run PHP-Scoper automatically when you run `composer install` or `composer update`. To do this, add the following to your `composer.json` file:
+
+```json
+"scripts": {
+ "php-scoper": [
+ "@php php-scoper.phar add-prefix --prefix=ProBlockBuilder",
+ "composer dump-autoload --working-dir build --classmap-authoritative"
+ ],
+ "post-install-cmd": [
+ "@php-scoper"
+ ],
+ "post-update-cmd": [
+ "@php-scoper"
+ ]
+}
+```
+
+That will run PHP-Scoper and update the autoloader after you run `composer install` or `composer update`. Read more [on the PHP-Scoper documentation](https://github.com/humbug/php-scoper/tree/main?tab=readme-ov-file#step-2-run-php-scoper).
+
+### 6. Follow [these directions to configure and instantiate the client](../configuration)
diff --git a/docs/Client/namespacing/strauss.md b/docs/Client/namespacing/strauss.md
new file mode 100644
index 0000000..89832b9
--- /dev/null
+++ b/docs/Client/namespacing/strauss.md
@@ -0,0 +1,90 @@
+---
+title: Namespacing with Strauss
+sidebar: auto
+sidebar_label: Strauss
+sidebar_position: 1
+---
+
+## Using Strauss
+
+Strauss is used for namespacing the Client to prevent conflicts with other plugins or themes that are using TrustedLogin. We recommend installing via the `strauss.phar` method.
+
+### 1. Install Strauss
+
+[Install Strauss](https://github.com/BrianHenryIE/strauss#use). Strauss is used for namespacing the Client to prevent conflicts with other plugins or themes that are using TrustedLogin. We recommend installing via the `strauss.phar` method.
+ 1. `cd` into your plugin or theme directory
+ 1. Run `curl -o strauss.phar -L -C - https://github.com/BrianHenryIE/strauss/releases/latest/download/strauss.phar`
+
+## Using PHP-Scoper
+
+If you prefer to use PHP-Scoper, you can follow the instructions [on the PHP-Scoper page](/Client/php-scoper.md).
+
+### 2. Install the TrustedLogin Client SDK
+
+1. Run `composer require trustedlogin/client:dev-main` to install the TrustedLogin Client SDK
+1. Run `composer require scssphp/scssphp --dev` to install `scssphp` as a dev dependency. This is used to generate and namespace the CSS used by TrustedLogin. If you already have `scssphp` installed, or are [using an alternative way to namespace the CSS](/Client/css-namespacing.md), skip this step.
+1. Update your `composer.json` file to integrate with Strauss. Follow the instructions as detailed in the [Strauss documentation](https://github.com/BrianHenryIE/strauss#configuration) for namespacing your plugin and theme. See example below.
+
+```json
+[...]
+ "require": {
+ "trustedlogin/client": "dev-main"
+ },
+ "require-dev": {
+ "brianhenryie/strauss": "dev-master",
+ "scssphp/scssphp": "^v1.11.0"
+ },
+ "autoload": {
+ "classmap": [
+ "vendor"
+ ]
+ },
+ "extra": {
+ "strauss": {
+ "target_directory": "vendor-namespaced",
+ "namespace_prefix": "ProBlockBuilder\\",
+ "classmap_prefix": "ProBlockBuilder_",
+ "classmap_output": true,
+ "packages": [
+ "trustedlogin/client"
+ ]
+ }
+ },
+ "scripts": {
+ "strauss": [
+ "@php strauss.phar"
+ ],
+ "trustedlogin": [
+ "@php vendor/bin/build-sass --namespace=ProBlockBuilder"
+ ],
+ "post-install-cmd": [
+ "@strauss",
+ "@trustedlogin"
+ ],
+ "post-update-cmd": [
+ "@strauss",
+ "@trustedlogin"
+ ]
+ }
+[...]
+```
+
+## 3. Run `composer update`
+
+Run `composer update` to update your dependencies. Strauss should generate a `vendor-namespaced/` directory. If it doesn't, you may need to run `composer install` first.
+
+### 4. Include the autoloader
+
+When using Composer, you likely already have added an autoloader to your code using something like `require_once 'vendor/autoload.php';`. If not, do so:
+
+```php
+require_once 'vendor/autoload.php';
+```
+
+If you set `classmap_output` to `false` in the Strauss configuration, you will need to include the autoloader in your code. If using the sample configuration above, the autoloader would be located at `vendor-namepaced/autoload.php` and the code would be:
+
+```php
+// For a plugin or theme:
+include_once trailingslashit( dirname( __FILE__ ) ) . 'vendor-namespaced/autoload.php';
+```
+### 5. Follow [these directions to configure and instantiate the client](../configuration)
diff --git a/docs/Client/troubleshooting.md b/docs/Client/troubleshooting.md
index 6a6349b..744db17 100644
--- a/docs/Client/troubleshooting.md
+++ b/docs/Client/troubleshooting.md
@@ -67,3 +67,20 @@ $config = [
```
If those are not the same, the CSS rules will not match the HTML generated and won't be applied.
+
+### If scripts aren't loading, check for a No-Conflict mode {#no-conflict-mode}
+
+Some plugins like Gravity Forms and GravityView have a "no-conflict mode" to limit script and style conflicts. If you see
+scripts and styles not loading on your Grant Support Access page, that's what's going on.
+
+The WordPress script and style handles registered by TrustedLogin are formatted as `trustedlogin-{namespace}`.
+Here's an example of how GravityView (with a namespace of `gravityview`) allows TrustedLogin scripts:
+
+```php
+add_filter( 'gravityview_noconflict_scripts', function ( $allowed_scripts = array() ) {
+
+ $allowed_scripts[] = 'trustedlogin-gravityview'; // ⚠️ GravityView's namespace is `gravityview`
+
+ return $allowed_scripts;
+} );
+```
diff --git a/docs/Client/usage.md b/docs/Client/usage.md
new file mode 100644
index 0000000..5ae3181
--- /dev/null
+++ b/docs/Client/usage.md
@@ -0,0 +1,62 @@
+---
+title: Using TrustedLogin
+sidebar_label: Using TrustedLogin
+sidebar: auto
+sidebar_position: 7
+---
+
+## Requesting access from customers
+
+Now that you've installed the TrustedLogin SDK into your plugin or theme, you can start requesting access from your customers. There are a few ways to do this:
+
+### 1. Point customers to the Grant Support Access page on their own site
+
+There's an easy way to do this: point them to their own login screen, with extra parameters that turns the login screen into a TrustedLogin "Grant Support Access" screen:
+
+**`https://example.com/wp-login.php?action=trustedlogin&ns=YOUR-NAMESPACE`**
+
+Replace `example.com` with the customer's domain and `YOUR-NAMESPACE` with the namespace you set up in the [TrustedLogin configuration](/Client/configuration).
+
+If you are using a support system that allows for dynamic variables, you can also pass a reference ID to the URL, making it easier to connect the Grant Access request to this specific support ticket: Add `&ref=YOUR-REFERENCE-ID` to the URL.
+
+#### Automating requests with Help Scout
+
+We suggest setting up Saved Replies in Help Scout that include the dynamic URL to the Grant Support Access screen. The URL in the saved reply can be dynamically generated so that The variable `{%conversation.number%}` will be replaced with the conversation number.
+
+Here's a Saved Reply template you could use in Help Scout (update `YOUR-NAMESPACE` with the appropriate values for your setup):
+
+```html
+Please visit this page on your website [UPDATE THE DOMAIN] and click "Grant Pro Block Builder Access". That will grant us temporary access to your site so that we can assist you with this issue.
+```
+
+Note: There's currently no way for Help Scout to dynamically insert the customer's URL, so you'll need to manually update the domain in the saved reply. We added an `[UPDATE THE DOMAIN]` reminder: the customer support agent will need to change the URL to match the customer's domain. Once the domain is updated, the agent can remove the `[UPDATE THE DOMAIN]` reminder.
+
+
+
+### 2. Integrating with your support form
+
+If you have a support form on your website, you can add a TrustedLogin field to proactively request access support while customers are creating their support ticket. This is a great way to streamline the process and make it easier for customers to grant access.
+
+We are in the process of creating TrustedLogin integrations with the following WordPress form plugins:
+
+- Gravity Forms
+- WS Form
+- Ninja Forms
+- WPForms
+- Formidable Forms
+- Contact Form 7
+- Forminator
+- Fluent Forms
+- Elementor Forms
+
+If you are using one of these form plugins, you can expect an update soon that will allow you to add a TrustedLogin field to your support form.
+
+## Adding reference IDs to Grant Access requests {#reference-ids}
+
+Reference IDs are useful when you want to attach a specific ticket ID or conversation ID to a login.
+
+Reference IDs can be passed via URL like so: `wp-login.php?action=trustedlogin&ns={namespace}&ref=[123]`
+
+When a Reference ID exists, users will see the reference while granting access:
+
+
diff --git a/static/img/client/saved-reply.png b/static/img/client/saved-reply.png
new file mode 100644
index 0000000..19e61dd
Binary files /dev/null and b/static/img/client/saved-reply.png differ