V2 Dynamic Site Creation (Event Based)

Introduction

This document describes how you can create Hovr custom site from your website on demand. Using integration token you can create a site from your portal with minimum required data.

📘
Prerequisites
New Integration
Before you can implement the easy on demand create site for your Hio Hovr integration, you need to request an integration token from your Hio Account manager. Once granted access for integration token you will locate the token via the admin portal.
The technical changes needed on your website/webapp are minimal but requires a web developer/engineer who can make changes to the backend and frontend of your website. This requires a moderate level of technical knowledge of your platform unlike the standard Hio Hovr setup that requires very basic understanding of your website and can be done by a non-technical person in most cases.
Upgrading From V1
Please reach out to your Hio Account Manager to enable the token generation process in the admin tool. We have upgraded our API token to bearer tokens. The last issued token will still work for V1 dynamic site creation however it will no longer work for V2. You will need to generate a new token via the admin portal.

Client Steps

Locate in your code where the event creation occurs for administrators. Provide them with the option to 'Add Hio' to their event.
Each event should have a unique URL. Before making the API call to create site creation make sure that you have what that URL will be.
Make the callout to Dynamic Site Creation endpoint from a backend method (Information about API is added below).

In order to use our API you must have an integration token. If you do not have one please reach out to your customer support representative.
We ask that this come from a backend method for a more secure API call.

Consume JSON response to indicate that the site was successfully created for the event.
Add the script below to the event's HTML inside the HTML head tag.

Example of Snippet of code to be added to HTML

<script id="hio-script-identifier" defer src="https://plugin.hiosocial.com/bundle.js" data-id=${site.id}></script>

How to Append Code Snippet to HTML Head Tag

//simulating already getting reponse from API call
const hovrSnippet = document.createElement("script");
hovrSnippet.type = "text/javascript";
hovrSnippet.src = "https://plugin.hiosocial.com/bundle.js";
hovrSnippet.setAttribute('data-id',${siteId});
document.getElementsByTagName("head").appendChild(hovrSnippet);

End Points

Production Environment:
https://prod-gcf.hiosocial.com/api/v2/integration/site/

Usage

Method:
GET-get site info
https://prod-gcf.hiosocial.com/api/v2/integration/site/
POST-site creation
https://prod-gcf.hiosocial.com/api/v2/integration/site/{siteId}
PATCH-update site
https://prod-gcf.hiosocial.com/api/v2/integration/site/{siteId}

Header

Field	Description	Required
Authorization	Bearer	Yes
Content-Type	application/json	Yes

Body(JSON)

Field	Description	Default	Required	Warning
name	String: Name of the site		Yes
subHeader	String: Site Header that appears on the hovr plugin.	We're making websites social, check it out.	No
integrationType	String Set values : "anyWebsite", “entireWebsite”, “specificSubdomain”, "pagesStartWith", "specificPage" (See Below for Additional Information)	N/A	Yes(if status is live)
integrationUrl	String Site URL	N/A	Yes
conversionUrl	String Site URL		No
primaryHexColor	String hex code for color	#002B61	No
secondaryHexColor	String hex code for color	#002B61	No
isNetworkingEnabled	Boolean is network card enabled	True	No
isOneToOneTextChatEnabled	Boolean is one to one chat enabled	True	No
isOpenChannelsEnabled	Boolean is open chat enabled	True	No
openChannelCreatePermission	String set values: "creator", "anyone"	creator	No
isOneToOneVideoChatEnabled	Boolean Enable one to one video chat(feature not available at this time)	False	No
isVipTableVideoCallEnabled	Boolean Enable vip table video chat(feature not available at this time)	True	No
isChatProfanityFilterEnabled	Boolean	True	No
numberOfChannels	String set values: "multipleChannels", "singleChannel"	multipleChannels	No
isSingleSignOn	Boolean	false	No	Marking this value true will cause the hovr to not appear until it receives the JWT token from our seamless sign on. If you are unsure of what this is please reach out to an account manger for more info.
status	String set values: "draft", "live", "unpublished"	N/A	Yes
cardConfiguration	See Below for Structure, this is an array	Default listed below	No
channels	See Below for Structure	N/A	Yes
isEmbedded	Boolean	false	No

integrationType additional detail

Option	Explanation
Multiple websites	Use this option if you would like to use this configuration on multiple website
Entire websites	Use this option if you would like to use this configuration on your whole website
Specific subdomain	Use this option if you would like to use this configuration on a subdomain and its extensions.
Pages start with	Use this option if you would like to use this configuration that start with a specific pathway and its extensions
Specific Pages	Use this option if you would like to use this configuration

cardConfiguration

Field	Description	Default	Required
customName	String Name of Card	N/A	Yes
textDescription	String About the card	N/A	Yes
cardIdentifier	Decimal set values: 1 for Networking, 2 for Open Chat Channels, 3 for Connection, 4 for Direct Message, 5 for FAQs & Privacy	N/A	Yes
hexPrimary	String hex color code	N/A	Yes
hexSecondary	String hex color code	N/A	Yes

cardConfiguration default

[
{
"customName": "Networking",
"textDescription": "Build relationships with interesting people.",
"cardIdentifier": 1,
"hexPrimary": "#002B61",
 "hexSecondary": "#c1c1c1"
},
{
"customName": "Open Chat Channels",
"textDescription": "Engage in live chat conversations.",
"cardIdentifier": 2,
"hexPrimary": "#002B61",
"hexSecondary": "#c1c1c1",
 },
 {
"customName": "Connections",
"textDescription": "Easily follow up and build relationships.",
"cardIdentifier": 3,
"hexPrimary": "#002B61",
"hexSecondary": "#c1c1c1",
},
{
"customName": "Direct Message",
"textDescription": "Send and receive 11 chat messages.",
"cardIdentifier": 4,
"hexPrimary": "#002B61",
"hexSecondary": "#c1c1c1",
 },
{
"customName": "FAQs & Privacy",
 "textDescription": "View Hio privacy, data, and security information.",
"cardIdentifier": 5,
"hexPrimary": "#002B61",
"hexSecondary": "#c1c1c1",
}
 ]

channels

Field	Description	Default	Required
title	string name of channel	N/A	Yes

Default Array

[
 {
	"title": "General Chat"
 },
 {
	"title": "Announcements"
 },
 {
	"title": "Intros"
 },
 {
 	"title": "Asks/offers"
 },
 {
	"title": "Random"
 }
]

Response POST

// 201 - Site Created

{
	"status": "success",
	"message": "Site created successfully.",
	"siteId": {hovr backend id},
	"embeddedCode": 
  		“<!-- Hio Web Plugin code starts here -->
  		<!-- paste this code on your website just before </body> tag -->           
      <div id=\"hio-site-identifier\" data-id=\{hovr backend id}\"> </div>
  		<script src=\"https://dev-plugin-helper.hiosocial.com/plugin_loader.js\">
  		</script>
  		<!-- Hio Web Plugin code ends here -->”
}

Response PATCH

//201 - Site Updated
{
	"message": "Site updated successfully.",
	"status": "success"
}

Response GET

//200 - site detail

{ 
	"data":{
    "cardConfiguration":[
      {
        "cardIdentifier": Number,
        "customName": String,
        "hexPrimary": String,
        "hexSecondary": String,
        "Icon": URL,
        "sortOrder": Number,
        "textDescription": String
    }],
    "channels":[
      {
        "channelUrl": String,
        "Id": Number,
        "sortOrder": Number,
        "Title": String
      }],
    "conversionUrl": URL,
    "id":Number,
    "integrationType":String,
    "integrationUrl": URL,
    "isChatProfanityFilterEnabled": Boolean,
    "isEmbedded":Boolean,
    "isNetworkingEnabled":Boolean,
    "isOneToOneTextChatEnabled":Boolean,
    "isOneToOneVideoChatEnabled":Boolean,
    "isOpenChannelsEnabled":Boolean,
    "isSingleSignOn":Boolean,
    "isVipTableVideoCallEnabled":Boolean,
    "name": String,
    "numberOfChannels":String,
    "openChannelsCreatePermission": String,
    "primaryHexColor": String,
    "secondaryHexColor": String,
    "status": String,
    "subheader": String,
    "type": String,
    "uuid": UUID
  },
 	"Success": Boolean
}

Response ERROR


400: Bad Request	{ "status": "failed", "message": "Error Message." "errors": { "field_name": "Error Message" } }
401: Unauthorized Server	{ "status": "failed", "message": "Error Message." }
404: Object Not Found	{ "status": "failed", "message": "Error Message." }
405: Method not allowed	{ "status": "failed", "message": "Error Message." }
500: Internal Server Error	{ "status": "failed", "message": "Error Message" }
503: Service Unavailable	{ "status": "failed", "message": "Error Message" }