February 10, 2017

Jscrambler 101 — First Use

by Jscrambler

Jscrambler 101 — First Use

Last updated on: October 18th, 2018

Welcome to Jscrambler 101! A collection of tutorials on how to use Jscrambler to protect your JavaScript. These tutorials cover Jscrambler version 5.4.

Introduction

In this tutorial — First Use — you will be introduced to our interface and we will guide you through the process of making your first protection request. You will learn how to create a template and use the API.

How to access your Dashboard

To start using Jscrambler, you have to sign in with the credentials you used to create your account. If you don't have a Jscrambler account, this is the time to create one by clicking Start your Free Trial! or going here.

The first time you open Jscrambler's web app, you will see a demo screen as shown below.

Jscrambler Demo Screen

In this demo, you have a sample code shown on the left side of the text editor. Follow the message bubble and click the Protect App button. Jscrambler will apply its most resilient protection techniques to the sample code and the protected code will appear on the right side of the text editor.

Now you can proceed to your own dashboard, simply by following the message bubble and clicking Dashboard on the top right menu.

Dashboard

To use your Dashboard, you must verify your email address.

In the Dashboard, hover the Playground App and select View App to enter. This Playground App will allow you to test all of our transformations applied to a sample file.

Inside the Playground App, in the File Tree on the left, you will see a pre-configured sample JavaScript file — an HTML5 racing game:

Playground Overview

If you click the sample JavaScript file common.js, you will see its content on the left side of the Text Editor:

File Tree Left

Now, let’s move on to the right side of the text editor. Here is where you will find the protected code after you apply a protection. You can also find three available tabs:

  • Application Modes — where you can set language specifications and what type of app will be protected;
  • Templates — where you can select one of our default templates (or use a template you created) in order to apply a saved set of transformations to the sample code.
  • Fine-Tuning — where you can select which individual transformations you want to apply to the source code;

Tabs

We'll now go over each of these tabs separately.

Application Modes

On this first tab, you will be able to set some details for your specific app. First, you have Language Specifications. This enables you to define the specification for which we can apply transformations. The protected code will be compatible with the specification you select here.

Below this, you should simply select the type of app you're looking to protect. This will help optimize Jscrambler's protected code for the environment where the app will run.

Fine-Tuning

On this tab, you can specify the code transformations you want to apply to the source code one by one.

On the top, you’ll notice there’s an Advanced Options switch. If you click it, you’ll get an additional set of options. This is because some of our simpler options are created by a set of advanced options.

As an example, if you tick the Identifiers transformation (with the Advanced Options turned off), you can then turn on the Advanced Options and see you're actually applying two transformations: Dot to Bracket Notation and Identifiers Renaming.

Simple vs Advanced

If you hover over each transformation in the Advanced Options, a brief explanation will appear on each one. Take this as an example:

Hover More Info


Side Note: How to clear selected transformations

After completing the step above, you’ll notice that you now have a Clear Selection option below the Fine-Tuning list. Should you want to deselect every transformation you selected, this will be the quickest way to do so.

Clear Selection


Templates

Templates consist of a saved set of code protections. As so, they enable you to apply multiple pre-defined protections without needing to choose them one-by-one every time.

On this tab, you will find Default Templates and Custom Templates. Default Templates are provided directly by us and contain sets of protections with self-explanatory purposes. As an example, the Advanced Obfuscation template will apply a set of protections which give your code the highest level of obfuscation.

Custom Templates consist of templates you created. Creating a template is simple: head over to the Fine-Tuning tab and select some protections. From there, just click the Create Template button below the transformations. Give your template a name and a description, click Save Template and you’re done!

If you go into Templates tab you should now see your new Template.

Creating a Template

Protecting your code

Now that we understand what protections are, let's protect our HTML5 racing game.

As you may remember, we can do this two different ways: either by picking protections one by one on the Fine-Tuning tab or by selecting a pre-defined template on the Templates tab.

Let's go ahead and test the Advanced Obfuscation template. Select it on the Templates tab. If you're curious to see which transformations this template includes, simply go to the Fine-Tuning tab and check for yourself.

We're ready to apply these protections. To do that, press Protect App at the bottom. After the app is protected, you will see the result on the right side of the text editor. If nothing shows up, just click on the common.js file. The result will be similar to this:

Protected Code

All protections you apply in the Playground won’t affect your account balance in any way — you can try everything without any worries.

How to download the protected code and test it

Downloading your newly protected code is straightforward: simply press Download App (bottom left) and that’s it.

The transformations we applied during this simple process already go a long way towards protecting your code. They are suitable for obfuscating your functions and objects and concealing their logic.

Now, you can test the newly protected file. To do that, extract the contents of the downloaded .zip file into a new folder, and open index.html. The HTML5 racing game should automatically open in your browser. You will notice it will run normally, even though it's using the obfuscated code.

Protecting with code locks

So far, we've successfully made our HTML5 racing game's code very hard to understand and reverse engineer. But let's say we want to take a step further and prevent this game from running on any domains except our own.

Under the Code Locks section of the Fine-Tuning tab, after selecting Domain Lock, you can specify (whitelist) domains where the app is allowed to run. Let’s see what happens when an app with a Domain Lock is opened in an unauthorized domain. To do this, input something like www.foo.com as the whitelisted domain.

Now, repeat the protecting process and download the app again.

Let's create a new folder called DomainLock, extract the .zip file of your newly protected app into it and open the index.html file. You will see that the app either won’t show up or will work badly because the code is not running on the whitelisted domain.

Moving forward, let’s change the domain into something we can work with. In this case, because we will be re-using the DomainLock folder you've just created, you can simply copy the path that shows up in the browser's navigator. It should look something like file:///C:/DomainLock/index.html.

Add this domain to the accepted domains and remove www.foo.com.

Protect and download the app again. Now, delete the contents of the DomainLock folder, extract the newly protected app there and run it. The game will be working properly again.

How to protect your own app

So far, we have covered the basics of Jscrambler by using the Playground app. Now, we will guide you through the process of protecting your own app. To return to the dashboard, either click on the Jscrambler logo at the top left corner, the Dashboard link on the menu, or simply click here.

Once there, you should click the Create App button, insert a name in the input like Test and click Create App to create your own Jscrambler project.

Create App

You should now be inside your application page, which will be similar to this:

New App Page

How to add your own file to be protected

On the left side of the screen, you have your file tree, where you can check which files have been uploaded to the app. You can add your JavaScript and HTML files or add a single Zip archive containing your project into the app.

If you click the "Add" button on the left, you can see that a file can be created directly from the interface, uploaded from your device, or obtained through a URL. Choose the most suitable option to add your app.

Add Files

After you have some files in your file tree, you can apply transformations to your code as you did on the Playground App — but this time you'll be protecting your own JavaScript files.

For tutorial purposes, let's choose Identifiers Renaming and Whitespace Removal as our transformations (find them after toggling Advanced Options, in the Fine-Tuning tab).

You can now protect your app with these transformations and check out what your protected code looks like. After that, it's ready to be downloaded and used. Remember you can always create new templates to apply these transformations later.

Downloading JSON file with transformations

If you're looking to use our API, you are able to download a set of transformations from the dashboard to be applied. To do this, click the blue download button next to the Application Settings.

Download JSON

This will download a JSON file with whichever transformations you have selected at the time. If you want to download a template, first you have to select it, and then you can download its options using the method we just covered. You should have downloaded a file similar to the one below:

{
  "keys": {
    "accessKey": "myAccessKey",
    "secretKey": "mySecretKey"
  },
  "applicationId": "myApplicationID",
  "params": [
        {
      "name": "identifiersRenaming"
    },
    {
      "name": "whitespaceRemoval"
    }
  ],
  "areSubscribersOrdered": false,
  "applicationTypes": {
    "webBrowserApp": false,
    "desktopApp": false,
    "serverApp": false,
    "hybridMobileApp": false,
    "javascriptNativeApp": false,
    "html5GameApp": false
  },
  "languageSpecifications": {
    "es5": true,
    "es6": false,
    "es7": false
  },
  "useRecommendedOrder": true,
  "jscramblerVersion": "5.4"
}

The AccessKey and SecretKey vary from user to user, while applicationId changes according to the application you are protecting. You can check your applicationId inside the app, above the text editor:

App ID

As for your AccessKey and SecretKey, you can check them in My Settings, under the "API Credentials" section:

API Credentials

A downloaded JSON file will be used in a following 101 article, which will detail how to use the CLI.

Conclusion

This concludes our first tutorial on how to use Jscrambler.

You should now be able to navigate easily through the available apps, create new projects, apply transformations to your code, save them as templates, and download them as a JSON file to be able to use the API. Feel free to proceed to our next tutorial, where we explore Code Annotations and their functionalities.

Enjoy your testing and start protecting your Applications ASAP! If you have any additional questions, feel free to contact us.