# SnapEngage – live chat

SnapEngage is a live chat widget for your site which integrates with your existing chat client. It integrates with many online applications and even allows you to make a remote screenshot of the webpage. SnapEngage can be customized to fit your website look and feel, offers reports and statistics and is available in many languages.

## Installation

To start using the SnapEngage integration, you must have installed the django-analytical package and have added the `analytical` application to `INSTALLED_APPS` in your project `settings.py` file. See Installation and configuration for details.

Next you need to add the SnapEngage template tag to your templates. This step is only needed if you are not using the generic `analytical.*` tags. If you are, skip to Configuration.

The SnapEngage Javascript code is inserted into templates using a template tag. Load the `SnapEngage` template tag library and insert the `SnapEngage` tag. Because every page that you want to track must have the tag, it is useful to add it to your base template. Insert the tag at the bottom of the HTML body:

    {% load snapengage %}
    ...
    {% snapengage %}
    </body>
    </html>

## Configuration

Before you can use the SnapEngage integration, you must first set the widget ID. You can customize the visitor nickname and add information to their status in the operator buddy list, and customize the text used in the chat window.

### Setting the widget ID

In order to install the chat code, you need to set the ID of the SnapEngage widget. You can find the site ID on the Your Widget ID page of your SnapEngage account. Set `SNAPENGAGE_WIDGET_ID` in the project `settings.py` file:

    SNAPENGAGE_WIDGET_ID = 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'

If you do not set the widget ID, the chat window will not be rendered.

### Customizing the widget

The SnapEngage widget can be customized in various ways using either context variables or settings. More information about controlling the widget can be found on the customization FAQ section of the SnapEngage website.

Setting | Context variable | Description
--- | --- | ---
`SNAPENGAGE_DOMAIN` | `snapengage_domain` | Manually set the domain name to follow users across subdomains.
`SNAPENGAGE_SECURE_CONNECTION` | `snapengage_secure_connection` | Force the use of SSL for the chat connection, even on unencrypted pages. (Default: `False`)
`SNAPENGAGE_BUTTON_EFFECT` | `snapengage_button_effect` | An effect applied when the mouse hovers over the button. (Example: `"-4px"`)
`SNAPENGAGE_BUTTON_STYLE` | `snapengage_button_style` | What the chat button should look like. Use any of the `BUTTON_STYLE_*` constants, or a URL to a custom button image.
`SNAPENGAGE_BUTTON_LOCATION` | `snapengage_button_location` | The location of the chat button. Use any of the `BUTTON_LOCATION_*` constants.
`SNAPENGAGE_BUTTON_LOCATION_OFFSET` | `snapengage_button_location_offset` | The offset of the button from the top or left side of the page. (Default: `"55%"`)
`SNAPENGAGE_FORM_POSITION` | `snapengage_form_position` | Configure the location of the chat window. Use any of the `FORM_POSITION_*` constants.
`SNAPENGAGE_FORM_TOP_POSITION` | `snapengage_form_top_position` | The chat window offset in pixels from the top of the page.
`SNAPENGAGE_READONLY_EMAIL` | `snapengage_readonly_email` | Whether a preset e-mail address can be changed by the visitor. (Default: `False`)
`SNAPENGAGE_SHOW_OFFLINE` | `snapengage_show_offline` | Whether to show the chat button when all operators are offline. (Default: `True`)
`SNAPENGAGE_SCREENSHOTS` | `snapengage_screenshots` | Whether to allow the user to take a screenshot. (Default: `True`)
`SNAPENGAGE_OFFLINE_SCREENSHOTS` | `snapengage_offline_screenshots` | Whether to allow the user to take a screenshot when all operators are offline. (Default: `True`)
`SNAPENGAGE_SOUNDS` | `snapengage_sounds` | Whether to play chat sound notifications. (Default: `True`)

There are also two customizations that can only be used with context variables.

Context variable | Description
--- | ---
`snapengage_proactive_chat` | Set to `False` to disable proactive chat, for example for users who are already converted.
`snapengage_email` | Set the e-mail address of the website visitor. (See Setting the visitor e-mail address)

### Setting the visitor e-mail address

If your website identifies visitors, you can use that to pass their e-mail address to the support agent. By default, the e-mail address of an authenticated user is automatically used. See Identifying authenticated users.

You can also set the visitor e-mail address yourself by adding either the `snapengage_email` (alias: `snapengage_identity`) or the `analytical_identity` variable to the template context. If both variables are set, the former takes precedence. For example:

    context = RequestContext({'snapengage_email': email})
    return some_template.render(context)

If you can derive the e-mail address from the HTTP request, you can also use a context processor that you add to the `TEMPLATE_CONTEXT_PROCESSORS` list in `settings.py`:

    from django.core.exceptions import ObjectDoesNotExist

    def set_snapengage_email(request):
        try:
            profile = request.user.get_profile()
            return {'snapengage_email': profile.business_email}
        except (AttributeError, ObjectDoesNotExist):
            return {}

Just remember that if you set the same context variable in the `RequestContext` constructor and in a context processor, the latter clobbers the former.

If the user should not be able to edit the pre-set e-mail address, you can set either the `snapengage_readonly_email` context variable or the `SNAPENGAGE_READONLY_EMAIL` setting to `True`.

Thanks go to SnapEngage for their support with the development of this application.