Managing Applications

How to manage your applications in the Platform Settings tab

Applications are managed in the Applications tab. An application uses a code snippet to apply a policy and other settings and configurations to a set of website pages. It is recommended to have at least two applications; one active and one for testing.

A list of existing applications is displayed on the left hand side of the Applications dashboard. Only one application can be active at any given time.
An application is comprises of four entities:

  • A selected policy
  • API Tokens
  • Custom Parameters
  • Code Snippet

Creating a New Application

To create a new application, click Create Application, enter the Application Name, and select the Policy from the account’s existing policies to apply on the application. One policy can be selected for an application.

The Duplicate button allows you to copy an existing application and then modify any configurations for the new application. A duplicated application will have the same name as the original application with "copy" at the end. For example, <application_name>copy. It is recommended to change the name of the new application.

Active/Bypass

Application can be set in Active or Bypass mode. Setting the application to Bypass mode disables detection and set the score to zero for all requests. In Bypass mode, the JavaScript Client functionality is limited to cookie management only.

An admin user can also check Empty JavaScript Client. In this case, an empty client will be used and no cookie will be set.

Policy

One policy can be selected for an application. This policy applies to all pages with the application’s snippet pasted in them.

  • Select the policy you want from the dropdown list.

To configure policies, navigate to Platform Settings > Policies and use the Policies tab. For more information about policies, see Managing Policies.

Tokens

Server Tokens

Server Tokens identify your server when using API calls between your server and the PerimeterX server. You can use more than one token.

Captcha Bypass Tokens

The Captcha Bypass Token allows you to bypass the Captcha challenge in testing environments.

The token is available in Platform Settings -> Applications -> [Application Name] -> Tokens -> Captcha Bypass Tokens

  1. Select +Add to generate the token then select Apply Changes
  2. Add the x-px-captcha-testing header with the token as the value so it will be included on the outgoing request.
  3. When presented with a CAPTCHA challenge, refresh the page and the CAPTCHA will be bypassed.

The request will go through as if the CAPTCHA was solved and a "good" cookie will be baked. The token can be used multiple times.

Custom Parameters

Custom parameters are easily added to the code snippet. They allow you to collect specific information that is used for aggregation and intelligence. Our recommendation is to have at least one customer unique identifier of your business logic.

  • For each custom parameter you want to specify (up to ten unique parameters) add the following line of code to the snippet - window._pxParamN = "<paramN_value>";
  • Values of the custom parameters must be in string format
  • After adding the parameters to the Javascript you must define them in the portal.

Naming Custom Parameters:

Each customer defined parameter must have a defined display name. For example “Custom Parameter 1” can be displayed as “Affiliate ID” in the Dashboard.

  1. Navigate to Platform Settings > Applications.
  2. Select the application from the left hand side bar
  3. Scroll to the “Custom Parameters” section at the bottom of the application settings page
  4. Click Add to add additional parameters.
  5. Select the parameter you want to define.
  6. Enter the display name in the Display Name field.
  7. Select whether to use a Query String (extracted from the URL query string) and if so, enter the string parameters.

📘

Note

If no query string is chosen, the values for the Custom Parameter are passed in the snippet.

  1. Click Apply Changes. Code enabling statistics collection for the parameter is added to the snippet.

Snippet

The snippet is a small section of JavaScript that activates PerimeterX functionality for your site pages. The snippet must be pasted into each page of the site.
The snippet is used to track page views and Custom Parameters. This data is then sent to PerimeterX servers and used to calculate a score.
The Snippet code window contains snippet code that is automatically created according to the account and any customer defined parameters you have added.

First-Party Sensor

It is recommended to use the First-Party Sensor, where the web sensor is served locally from your domain.

The following Enforcers versions support First-Party configuration:

  • .NET v2.5.0 and higher
  • Apache v2.9.0 and higher
  • Apache Core v2.9.0 and higher
  • AWS Lambda v1.3.0 and higher
  • Citrix v1.0 and higher
  • Cloudflare v1.1.0 and higher
  • F5 BIG-IP v2.3.0 and higher
  • Fastly VCL v2.7.0 and higher
  • Go v2.0.0 and higher
  • Java v5.0.0 and higher
  • Kong v1.2.0 and higher
  • NodeJS v1.1.0 and higher
  • NGINX v3.1.0 and higher
  • NGINX Core v3.1.0 and higher
  • Python v2.0.0 and higher
  • Salesforce v18.2.1 and higher (no XHR support) 

📘

Note

For certain Edge Enforcers, such as Fastly, the sensor sends the First-Party XHR by default

Using the First-Party sensor provides:

  • Improved performance - Serving the sensor as part of the standard site content removes the need to open a new connection to PerimeterX servers when a page is loaded.

  • Improved detection - Third-Party content may be blocked by certain browser plugins and privacy add-ons. The First-Party sensor leads directly to improved detection, as seen with customers who previously moved from Third-Party sensor to First-Party sensor.

Configuring the First-Party Snippet

  1. To use the default First-Party routes, ensure that your PerimeterX Enforcer (and Enforcer version) supports the built-in First-Party sensor.

  2. Click the toggle to start configuring the First-Party snippet. In the default configuration, two routes are displayed.

These routes must be accessible on the web-server:

  • /<PX_APP_ID without PX prefix>/init.js
  • /<PX_APP_ID without PX prefix>/xhr

If these routes are not accessible prior to the snippet deployment, the web sensor will not be fetched.

📘

Note

For NGINX, Apache, NodeJS and Kong, this may require additional setup on your web-server. Please see specific enforcer documentation for more details on how to set it up.

If you are using the Salesforce Cartridge, click the checkbox, and click Activate First-Party.

Activating the First-Party Snippet

Click Activate First-Party to generate the First-Party snippet that is copied to the website.

The Third-Party snippet will continue to work regardless of whether the First-Party snippet is activated.

First-Party Snippet Advanced Configuration

Advanced configuration should only be performed by experienced users who are familiar with CDN and content caching rules, or with guidance from PerimeterX support [email protected].

📘

Note

If you wish to use a different set-up to serve the First-Party sensor, either through your CDN or CNAME records to point to PerimeterX servers, you must first configure these routes in your CDN or via DNS records.

  1. Ensure the following routes are pre-configured and working properly:

Sensor route

  • Fetching the JS Sensor and respecting caching headers from: //client.perimeterx.net/<PX_APP_ID>/main.min.js

Server route

  • Properly proxying traffic to and from PerimeterX servers: //collector-<PX_APP_ID>.perimeterx.net/api/v1/collector

  • By default, server communication is done directly to and from PerimeterX server, therefore this is an optional value.

<PX_APP_ID> can be found in the Platform Settings -> Applications section.

📘

Note

When proxying a request to PerimeterX you must set the correct host header of client.perimeterx.net or collector-<appid>.perimeterx.net to avoid any service interruption. If you do not add the host header, your request may not return the desired results.

  1. Click Advanced Configuration to use the custom values as the First-Party routes.

  2. Input the pre-configured routes:

  • Sensor route - Mandatory

  • Server route - Optional

  1. By default, the Server route will be used as fallback if PerimeterX servers cannot be reached by the JS Sensor.
    Check the box below the Server route ("Use 'Server' route as primary") to use it as the primary route for all server communication.

  2. Click Activate First-Party to generate the First-Party snippet that should be copied to the website.

The Third-Party snippet will continue to work regardless of whether the First-Party snippet is activated.

Snippet configuration may be edited at a later point to make any required changes, including advanced configuration.

Third-Party Sensor

Third-Party Sensor does not have prerequisites for deployment, however it lacks the advantages of the First Party Sensor.

Activating the Third-Party Snippet

Click Activate Third-Party to generate the Third-Party snippet that is copied to the website.

Custom Snippet Parameters Configuration

This section is applicable to both First-Party and Third-Party Snippets.

  window._pxParam1 = "<param1_value>";
  window._pxParam2 = "<param2_value>";
  var p = document.getElementsByTagName('script')[0],

Example: Extracting a cookie value into a custom parameter

  <script type="text/javascript">

    // Original JavaScript code by Chirp Internet: www.chirp.com.au
    // Please acknowledge use of this code by including this header.

    function getCookie(name)
    {
      var re = new RegExp(name + "=([^;]+)");
      var value = re.exec(document.cookie);
      return (value != null) ? unescape(value[1]) : null;
    }
  </script>

  <script type="text/javascript">
    (function(){
      // Custom parameters
      window._pxParam1 = getCookie('my_first_cookie');
      var p = document.getElementsByTagName('script')[0],
      s = document.createElement('script');
      s.async = 1;
      s.src = '//client.perimeterx.net/APP_ID/main.min.js';
      p.parentNode.insertBefore(s,p);
    }());
  </script>

Pasting the Code Snippet into your Site Pages

To paste the code snippet:

  1. Click Copy Snippet.
  2. Paste the copy of the code snippet into your web application pages using your preferred method (tag manager, header manager, etc). Best practice is to place the snippet right before the open tag in the HTML. Dashboard statistics start accumulating as page views immediately upon saving the site pages with the snippet.

📘

Note

The code snippet is loaded asynchronously in a non-blocking way so it will not slow down your site.

Page Types Mapping

PerimeterX's Page Types Mapping tool improves detection and helps protect your application better by mapping application paths to specified page types. Once PerimeterX has accumulated enough data from your application, your site is mapped, and your main site paths are divided into specified page types.
Mapping the regex path to the page type helps improve PerimeterX detection according to the page types.

Page Types is how PerimeterX divides the various types of pages in your application (Purchase, Checkout, Login, etc.).

When your site has been mapped, the Page Type, Path Regex, HTTP Method, and whether or not the path is In Use are displayed in the Page Types Mapping section under Platform Settings -> Applications.

Site paths which are not automatically mapped can be added manually. It is recommended to wait until PerimeterX finishes mapping your site before adding site paths manually. Site paths that have already been mapped can be edited.

PerimeterX Page Types:

  • Login & Authentication - Login or authentication associated paths
  • Checkout - Paths associated with checkout process
  • Purchase - Paths associated with cart, payments etc.
  • Products and Search - Paths associated with products info, as well as searching for products.
  • API Call - Paths associated with other APIs, but not directly to the website.
  • Resource - Paths for website resources such as html pages, CSS, images etc.

To add a new path:

  1. Click Add a Path to add and select the page type of a new path in your site.
  2. Enter the Path, and select the Page Type of your path from the dropdown options.
  3. Where relevant (Login page type) add the relevant HTTP methods.
  4. Click Save.
  5. When done with all changes click "Apply Changes".

📘

Important

If you do not click Approve, the mapping will not be applied.

The Path must be written as a regex. For more information on regexes see Regular Expressions

To delete an existing path:

  1. Click the trash icon button on the requested path row .
  2. Click OK to confirm that you want to delete the mapping path.
  3. When done with all changes click "Apply Changes".

To edit a path:

  1. Click the pencil icon to edit the relevant mapping path. In the Edit pop-up, make the necessary changes to the mapping path, and click Save.
  2. When done with all changes click "Apply Changes".

Did this page help you?