Support → Documentation → JavaScript Obfuscator suite → Users guide

1. Make sure you know about online commandline builder for JS-Obfus
2. Prepare makefile
3. Update use of symbol names in the modules
4. Test your original code with all modifications necessary for protection applied
5. Collect names of symbols that should not be modified.
6. Test protection with "lite" protection applied

# Steps in detail

## Make sure you know about online commandline builder for JS-Obfus

Make sure you are aware of Stunnix interactive online commandline builder. It not only helps to build command lines, but can be used as a Table Of Content for the JS-Obfus manual.

## Prepare makefile

Prepare a Makefile for a Make utility or compose a script that will perform protection for your entire project; make sure that it allows to edit commandline options applied to all invokations of JS-Obfus in a single place. It will be very useful since you will have to run JS-Obfus on your entire project several times, with different settings.

## Update use of symbol names in the modules

Find all places in your code that uses symbol names to make a reference. Add the following lines to the begining of those files (or make sure that the definitions of these functions are visible to your code from some base module):

    function OBJNAME(n) { '';return n; }

If the name of the symbol is a string constant, wrap it into the call of OBJNAME function (passing the name of the symbol in single quotes, without any spaces between parenthesis and quoted symbol name:

    //before
        var varname = "myvar";
        eval(varname + '= 23;");
    //after
        my $varname = OBJNAME('myvar');
        eval(OBJNAME('varname') + ' = 23;');

If your code uses some string that comes from external source as a name of the symbol, list all possible names of symbols as exceptions. E.g. the example below you will have to list 'f1' and 'f2' as exceptions in the 'exceptions.txt' file, otherwise your code won't work once protected since there won't be functions with names 'f1' and 'f2' (there would be functions with names something like z343a1b034 and z5e915db6).

    function f1 {}
    function f2 {}

    var fnnm = document.forms['form1'].myentry;
    eval(fnnm + '()');

## Test your original code with all modifications necessary for protection applied

Make sure your original code, after making all modifications described in the steps above, works as the code before your modifications.

## Collect names of symbols that should not be modified.

There can be several reasons a symbol should not be replaced with a meaningless string - most frequently case is when the symbol is in external module that is shipped in non-protected form (e.g. some library you don't have permission to modify or functions defined in ActiveX control) or is a name of document element (used by your code in statement like 'document.all.para1' or formfield name used by your code like this: document.forms[1].radio_name) or used in CSS files inside expression statement, or just simply should stay the same because your project is library and the symbols are public entries into it. Another case is when some symbols are used from the parts of your application, that are not obfuscated - e.g. from html strings with embedded javascript code that you don't plan to alter by marking names of symbols with OBJNAME() call.

There are several options available on how to do this:

1. For generating list of symbols from external JavaScript libraries, one can use semi-manual method - extract all symbols used by your code by running JS-Obfus over all files of your project with commandline option -D somefile.txt), and then find all symbols in 'somefile.txt' that come from external libraries.
2. For generating list of IDs and NAMEs of html elements and form fields, you can use get-idents-from-html.pl utility shipped with JS-Obfus, by running it over all your html files, like this

       	perl get-idents-from-html.pl -i htmlidents.txt file1.html file2.html file3.html

3. For symbols that are defined in public interface of ActiveX or OLE component, it's possible to extract names of these symbols using Project Manager. Start Project Manager, go to the Tools menu and select 'Extract symbols from ActiveX components' (this menuitem is available only on Windows platforms). For each component your project uses, select the component, click 'Extract' button, and you will be prompted to save a list of exceptions extracted from the component to the file of your choice. Please note that Evaluation and Demo editions don't offer this functionality (empty file will be produced).
4. Produce list of exceptions manually. Sometimes this is necessary even for symbols from external library modules too. Just add them to the file (e.g. named 'symlist.txt') one per line.

## Test protection with "lite" protection applied

Apply "lite" protection to your application, and test as much of your app as possible (i.e. try to perform all operations, or at least most common). The 99% of the problems encountered when trying to run protected app is that some symbol from external module was not listed as exception, and got replaced with different name. Once run, you will get errors like "Object is required: z34ea8c" in places where original code calls "document.all.myentry.value" and "myentry" is not listed as exception. In order to easily identify that "z34ea8c" should stand for "myentry", one should to use "lite" protection, that will make symbols only slightly less understandable, but different from original, e.g. you will get errors like "Object is required: Z439Z_myentry", that will signal you that "myentry" is not listed as exception. The following commandline will stand for "lite" protection:

    perl js-obfus -jam 0 -i prefix -n none -s none -e 0

that will stand for "Jam spaces and newlines: off", "Number of encoding iterations applied: 0 - don't encode", "Obfuscation of symbol names: none", "Obfuscation of integer constants: none", "Obfuscation of strings: none" options in interactive online commandline builder.

Once your app works correctly once such "lite" protection is applied, you should apply "final" protection, using options you wish. If such "finally-protected app" works differently, revert commandline options back to "lite" protection, and turn on each type of protection incrementally, e.g. turn on "Obfuscation of integer constants", then "Obfuscation of string constants", then "Number of encoding iterations applied: 4", testing your app one each step.

If something still doesn't work, make sure you've read recommendations in NOTES section in JS-Obfus manual.