Apologist Beacon is a compact version of Apologist Agent that can be customized and embedded on any website. Churches, Christian ministries, or any webmaster that wants wishes to enhance their website or web app with the power of Agent can simply add an HTML snippet to surface Beacon to their users. Click on the Beacon icon floating on the lower right of this page to see a live demo!
For more information about the features of Apologist Agent itself, check out the Apologist Agent Overview.
How to Embed Beacon on Your Website #
Adding Apologist Beacon to your website is easy. Paste this HTML snippet before the end of your page’s </body> tag:
<script async id="apg-beacon" src="https://apologist.ai/beacon/agent.min.js"></script>That’s it! You should see the Beacon icon floating in the lower right of your web page where you added the above snippet. If you wish to customize how Beacon is displayed, read on.
Configuration Options #
Build a Custom BeaconApologist Beacon supports the following options, all of which can be passed via the snippet as data attributes on the <script> tag:
User Identification #
Apologist Beacon allows you to pass in a custom user ID to tie the user back to your system. Simply pass your identifier via the data-user parameter, and all prompts the user submits will be tagged with that identifier.
Display Modes #
Apologist Beacon can be embedded using one of 3 modes using the data-mode parameter:
Corner (default) #
Set the data-mode parameter to “corner” (or don’t supply data-mode) to place Agent in the lower right of the screen. Agent will launch from the launcher icon’s position in a small window that won’t cover much of the screen (depending on the screen size), allowing users to still see and interact the host website. This mode will place the launched Agent in a similar location to where users would expect to find customer support widgets. Clicking the close icon or anywhere outside Agent will hide it.
Modal #
For a more immersive experience, set the data-mode parameter to “modal”. When Agent is launched, a semi-transparent overlay will automatically be placed over website content, and Agent will be displayed in the center of the user’s screen in a modal. By default, the overlay is white; however, you can override this by supplying the data-overlay-theme parameter as “dark”. Clicking the close icon or anywhere outside Agent will hide it.
Inline #
To place Agent in the flow of your website for a more integrated experience, set the data-mode parameter to “inline”. You must also supply the id attribute of an HTML element via the data-target parameter. The “inline” mode is assumed if the data-target parameter is supplied. Agent will automatically be injected into the target element and will fill the target elements dimensions (if set). You may control the size of the Agent window by adjusting the dimensions of the target element. Unlike the “corner” and “modal” modes, the “inline” mode has no launcher icon and is not opened or closed; it just appears in the flow of the content on page.
Sizing #
Agent defaults to sensible sizing based on the display mode, as described above in the Display Modes section. However, you may supply a custom width and/or height via the data-width and data-height parameters, respectively. Both parameters accept any valid CSS measurement.
Launcher Icon #
Icon Color #
By default, the Beacon icon will be whatever color you set as the “Primary Color”. However, if you wish the icon to be a different color than your primary color in the chatbot, you may override this behavior using the data-icon-color parameter. Any valid CSS color value is supported.
Icon Image #
If you would like to replace the Beacon icon image with a custom image, you may override it via the data-icon-image parameter. URLs and data URIs are supported. You may upload an image via Ignite if you wish, rather than hosting the image yourself.
Icon Position #
Some websites already have a floating icon in the lower right, or have some other obstruction that necessitates adjusting the position of the Beacon icon. In such cases, the Beacon icon position can be adjusted using the data-offset-x and data-offset-y parameters to control how far from the right and bottom edges of the screen the icon should be positioned, respectively. Any valid CSS measurement value is accepted for both offsets.
Icon Tooltip #
You may optionally include a persistent tooltip above the launcher icon to draw more attention to or explain the launcher. Supply any custom text in the data-tooltip parameter. The tooltip will always appear above the launcher icon, even if you change the position of the launcher icon. The tooltip will always appear as a single line without any line breaks. By default, the tooltip has a semi-transparent white background. To change the color of the background to a darker color, set the data-tooltip-theme parameter to “dark”.
Internal Agent Customizations #
Theme #
Apologist Beacon supports both light and dark themes via the data-theme attribute. It defaults to “dark”, but you can pass in a value of “light” to change it.
Primary Color #
You may pass in a custom primary color to Apologist Beacon by using the data-color attribute. Any valid CSS color value is supported. e.g., “#990000”.
Language #
Apologist Beacon currently supports nearly 200 languages out of the box. See the full list of supported languages here.
Use the data-language attribute to pass in a language code (e.g., es for Spanish). If no language is specified, Apologist Beacon will default to English. Note that due to limitations of the underlying Large Language Model (LLM) that powers Apologist Agent, some languages may yield better results than others.
You may also pass a data-languages attribute as a comma-delimited list to specify which languages users may switch to, and in which order. e.g., data-languages="en,es,zh".
Bible Translation #
The data-translation attribute instructs Agent to reference a specific Bible translation. English Standard Version will be used by default. Pass in the translation’s abbreviation in lower case. See the full list of supported Bible translations here.
In addition, you may pass a comma-delimited list of translation abbreviations via the data-translations attribute to control which translations will be available for users to select, and in which order. e.g., data-translations="esv,bsb,nasb".
Intro Screen Messaging #
The intro screen messaging is controlled by 3 attributes:
data-preamble: the medium text above the large, colored headline. Default: “Be curious. Be humble.”data-headline: the large colored text in between the headline and the description. Default: “Learn boldly.”data-description: is the small text below the large, colored headline. Default: “Ask anything about God, Jesus, or the Bible. This is AI for seekers of spiritual truth.”
If your Beacon supports multiple languages, you may add a valid JSON object for each of these attributes with language code keys. For example:
data-headline='{
"en": "My headline",
"zh": "我的标题"}'
Scrolling Behavior #
By default, Beacon will automatically scroll as the response is being output. However, you may change this behavior by adding data-autoscroll="false" to the script tag.
Message Persistence #
By default, Agent will reset automatically each time it’s launched, and any prompts the user entered will be lost. To change this behavior to persist prompts and responses even after Agent is closed, supply the data-persist parameter as “true”.
Other Customizations #
If there are customizations you would like to make to the appearance of the Beacon icon that are not supported through the above options, you may also simply override the Beacon icon’s styles via CSS. Here is a reference to the elements you may modify using custom CSS:
apg-iframe: The element in which Agent is displayed.apg-icon: The icon that launches Agent.apg-overlay: The overlay that is displayed over your website but behind Agent when displayed as a modal.apg-tooltip: The tooltip that is displayed just above the launcher icon. Note that this element is inside theapg-iconelement.
Full Example with All Options #
<script
async
id="apg-beacon"
data-user="[custom user identifier]"
data-mode="[corner|modal|inline]"
data-overlay-theme="[light|dark]"
data-target="[id attribute of your container element]"
data-width="[any valid CSS measurement]"
data-height="[any valid CSS measurement]"
data-language="[ISO 639-1 language code]"
data-languages=[comma-delimited list of language codes]"
data-translation="[esv|niv|bsb|kjv|net|nkjv|nlt|csb|nasb|tlv|cjb]"
data-translations=[comma-delimited list of translation abbreviations]"
data-theme="[light|dark]"
data-color="[any valid CSS color]"
data-preamble="[your preamble text or JSON object]"
data-headline="[your headline text or JSON object]"
data-description="[your description text or JSON object]"
data-autoscroll="[true|false]"
data-icon-color="[any valid CSS color]"
data-icon-image="[any image URL or data URI]"
data-offset-x="[any valid CSS measurement]"
data-offset-y="[any valid CSS measurement]"
data-tooltip="[your tooltip text]"
data-tooltip-theme="[light|dark]"
data-persist="[true|false]"
src="https://[your domain]/beacon/agent.min.js"
></script>Interacting with the Embedded Agent #
Apologist Beacon is designed to be flexibly integrated. The host web page may interact with it using the supplied Javascript API. Below are some ways that you may apply custom scripting to control the embedded Agent:
Controlling Agent Visibility #
There are 3 utilities for hiding and showing Agent when embedded:
apg.open(): Opens Agent (if closed).apg.close(): Closes Agent (if open).apg.toggle(): Toggles Agent visibility (opens if closed, closes if open).
The simplest use case would be apply an onclick handler to an element on your webpage which calls apg.open() to launch Agent programmatically.
Controlling Agent Functions #
You may send a prompt to Agent programmatically by calling apg.sendPrompt('your prompt'). This may be useful in cases where the host web page has content you wish the user to engage with by generating an Agent response once the user clicks to learn more about a given topic.
You may also reset the conversation in Agent at any time by calling apg.reset().