.. _installation_js:

JavaScript
==========

Apptimize supports client-side web, mobile-web, and hybrid mobile app testing through
our JavaScript SDK.

At this time, the JavaScript SDK supports programmatic experimentation (Dynamic
Variables and Code Blocks), but does not allow you to make visual changes using the
Visual Editor.

EU Cloud Site
^^^^^^^^^^^^^

Use the ``configAttributes`` flag to set your Apptimize region to EUCS if you are integrated in our EU Cloud site.


.. tabs::
    .. code-tab:: javascript JavaScript

        var apptimizeAppKey = 'YOUR_APP_KEY';
        var configAttributes = {
            'apptimize_region': 'eucs',
        };

        Apptimize.setup(apptimizeAppKey, configAttributes);


SDK Installation
^^^^^^^^^^^^^^^^

`Sign in <https://apptimize.com/admin/>`_ to the Apptimize dashboard. You’ll see a welcome
page that asks for the :ref:`name of your app<app_creation>`. After entering all your
info, you’ll see these installation instructions again.

You can find our latest `JavaScript API Documentation here <https://sdk.apptimize.com/js-client/docs/latest>`_.


Install with NPM
----------------

Install the SDK from the command-line with :code:`npm i @apptimize/apptimize-web-sdk`

Then, include Apptimize in your app using :code:`import`:

.. tabs::
    .. code-tab:: js JavaScript

        import Apptimize from '@apptimize/apptimize-web-sdk';
        // You can also use 'require' for a non-ES6 option.
        // var Apptimize = require('@apptimize/apptimize-web-sdk');

Our package can be found on npm `here <https://www.npmjs.com/package/@apptimize/apptimize-web-sdk>`_.

Install Directly
----------------

The SDK is also available as a downloadable package which comes bundled with all external dependencies.

1. Download the latest JavaScript SDK from the :ref:`SDK Download <sdk_download_and_documentation>` page.

2. Copy the SDK to your project directory, like an :code:`include` or
   :code:`scripts` directory.

3. Reference the SDK in your code: :code:`<script src="<path-to-sdk>/apptimize-js-client-<version>.bundle.min.js"></script>`.

Including the script will make the Apptimize API available as :code:`window.Apptimize`.


Initializing Apptimize
^^^^^^^^^^^^^^^^^^^^^^
To initialize Apptimize, call the :code:`setup()` method with the App Key associated
with your app, which can be found in the Install tab of your Dashboard.

**Synchronous and Asynchronous Loading**

To ensure the best experience for your end users, we recommend waiting to display page
content until Apptimize has been fully loaded and initialized. This will prevent potential
issues with users seeing multiple variants ("flickering" of visual elements) and
will prevent situations where an outsized percentage of users are placed in the baseline
variant because the experiment data hasn't been fully received and processed by the SDK.

The sample code below shows how to use :code:`setOnApptimizeInitializedCallback()` to
determine when Apptimize setup and initialization is complete.


.. tabs::
    .. code-tab:: javascript JavaScript

        // Create a function that will be executed whenever new Apptimize metadata is downloaded
        function onApptimizeInitialized(){
            console.log("Apptimize setup and initialization complete");
            Apptimize.track("Apptimize Initialized");
            // Set a flag to indicate Apptimize data is available and content can be displayed
        }

        Apptimize.setOnApptimizeInitializedCallback(onApptimizeInitialized);
        Apptimize.setup("<appkey>");


Single-Page Web Apps
^^^^^^^^^^^^^^^^^^^^
The Apptimize JavaScript SDK supports popular single-page web application
platforms such as React and Angular.

A simple example of an implementation of Apptimize in a basic React application is shown below
as a demonstration. In this example, Apptimize has been installed using
:code:`npm i @apptimize/apptimize-web-sdk` as described above.

.. tabs::
    .. code-tab:: jsx JSX

        import React, { Component } from 'react';
        import logo from './logo.svg';
        import './App.css';
        import Apptimize from '@apptimize/apptimize-web-sdk'

        class App extends Component {
            constructor(props) {
                super(props);
                this.state = {
                    isApptimizeSdkReady: false,
                    variantString: null
                };
            }

            componentDidMount() {
                // Create a function that will be executed when Apptimize sdk has been initialized
                let onApptimizeInitialized = function() {
                    this.setState({
                        isApptimizeSdkReady: true,
                        // Set dynamic variable values
                        variantString: Apptimize.getString("My Dynamic Variable", "Default value"),
                    });
                }.bind(this);
                Apptimize.setOnApptimizeInitializedCallback(onApptimizeInitialized);
                Apptimize.setup('<appkey>');
            }

            render() {
                if (!this.state.isApptimizeSdkReady) {
                    return null;
                }
                return (
                        <div>
                            Dynamic Variable Value: {this.state.variantString}
                        </div>
                );
            }
        }

        export default App;