Appgree in my website

Integrate Appgree with Login&Register

If you want your users to be registered automatically in your Appgree team, you’re in the right place. Below you can find information on how to do a light integration in your website or application of one of the most important components of Appgree, the widget.

This integration guarantees the security and confidentiality of the information: only the users of your platform will have the right to see and participate in your Appgree questions.

What is a widget?

Before proceeding, please visit the following sections:

How to integrate the widget

The aim of this section is to analyze the different ways to integrate the Appgree widget in a HTML webpage, taking as an example the Latest question widget.

A question widget is a piece of code that allows you to view the most recent question of the chosen Channel.

As you can see, the widget is a user-friendly, reduced-size component that can be inserted into any website, whether it’s placed into a modal dialogue box, in the main body of a website or sidebar, among other options.

Getting started

To make sure your integration has been successful, get in touch with Appgree by emailing us at support@appgree.com and ask for a validation. Once this is done, and before you carry out the integration, it is important that you familiarize yourself with the following concepts:

Token

Appgree provides a confidential security token named “SecretKey”, whose value is similar to: mlsdfkm234l91981723lq123098123eweqoiej. This token must be used by the integrator to process the requests through the Appgree API Rest.

This “secret” is used to calculate the “ApiKey”, which is required in the most important request of the process, that is, the creation/login of the user inside Appgree’s infrastructure. This creation/login is conducted via the request “login&register”. In this way, the integrator can dynamically register as many users as they want using the API Rest requests mentioned above, but with security measures that enable only the person who knows the “SecretKey” to perform the operation, doing so in the proper private team.

Keep in mind: Ideally the ApiKey will be calculated in backend so the SecretKey is not publicly exposed.

Sending of user data

The previous call allows you to send all the user data required by the integrator to the Appgree application:

  • Email. For this field, the integrator can simulate an email drawn from the concatenation of an internal identifier of the user in their platform, together with a “fake” termination such as “@organizacion.com”. In this way, Appgree will accept the sent format so that later on they may extract aggregated reports.
  • ExternalId. It is an external and univocal identifier, which the integrator provides in the call. Generally it is an identifier that in the information systems of the integrator is unique, in this way the maintains a correspondence with the users of Appgree. In case of not having an identifier, the integrator must enter the user’s email.
  • FirstName. User name. Only applies to questions with no anonymous answers set.
  • LastName. User surname. Only applies to questions with no anonymous answers set.
  • Attributes. User attributes. Attributes that the integrator finds useful for subsequent mining of the data.
  • ApiKey. Result from calculating “Md5” (email concatenated SecretKey).

Let’s look at an example of the definition of this type of call in REST format:

POST /rest/v1/sessions/external?apikey=234hk5j43234kjhmnb123kjhu123 HTTP/1.1Host: domain.appgree.com{"email":"usuario@domain.com","externalId":"100002344","firstName":"Luis","lastName":"Mendoza"}

Team identifier

Additionally, the integrator must know the identifier of the team, which corresponds to the reserved domain (Appgree team URL). As an example, for the team “madrid.appgree.com” the identifier could be spaceId=12339871231243, which would be used in another part of the API call explained below.

Cookies generation

Via this request, which is first performed when the page -where the widget is integrated- is loaded, the session cookies are generated so that they are available in the browser where the chosen widget will load. In this way, the widget and following participation requests will recognize the validated session, allowing the user to participate in the question.

An example of an integration with a “Javascript” and “HTML” code appears below; this integration uses the framework “jQuery”:

var email = getParameterByName('email'),externalId = getParameterByName('externalId'),firstName = getParameterByName('firstName'),lastName = getParameterByName('lastName'),attr1 = getParameterByName('attr1'),attr2 = getParameterByName('attr2'),.....language = detectedLang,apikey = getParameterByName('apiKey'),domain = getParameterByName('equipo');
var data = JSON.stringify({email: email,firstName: firstName,lastName: lastName,language: language,externalId: externalId,userAttributes: {attr1: attr1,attr2: attr2,.....}});
$.ajax({type: 'POST',url: domain + "/rest/v1/sessions/external?apikey=" + apikey + "&spaceId=00000001",data: data,contentType: 'text/plain',xhrFields: {"withCredentials": true},async: true,context: this,dataType: 'json',complete: loadIframe,timeout: 30000  // sets timeout to 30 seconds});

 

This fragment of code shows how the value “spaceId” is specified in the “URL” field from the Ajax request and how the “callback” function is assigned to treat the result of the request. Once the “HTTP 200 OK” code is received -code that indicates that the registration of the user was successful- you must load the widget. In the following paragraph, we delve into this latter point.

Ways to integrate

This section establishes the different ways to integrate the widget.

Popup or website belonging to the integrator

This format enables the viewing of the widget in a popup dialogue box or a complete website that belongs to the integrator. For both cases, the integrator can decide whether to wrap up the widget with information inviting the user to participate or not.

This is an example of widget integration in a website that belongs to the integrator:

integra_appgree4biz_widget_5

Steps for the integration

The following steps are used in an integration:

  1. Execution of the call “login&register” which allows you to obtain the validated session cookies when the page is loaded.
  2. Detection of the correct loading event via the error code “HTTP 200”.
  3. Loading of the widget via the following HTLM code:
    <div style="border: 1px solid #c8c8c8; margin: 0; padding: 0; max-width: 100%; height: {{height}}px; width: {{width}}px;"> <iframe src="https://equipo.appgree.com/widget.html?type=topic&class=appgree_widget&talk=2064834273533292545&topic=last&theme=equipo&login_mode=LOGIN_RESULTS" scrolling="no" frameBorder="0" style="border: none; width: 100%; height: 100%;"></iframe> </div>
  4. Question content automatically shown when the validated session cookies are validated.

From then on, the user will be able to participate in the question.

Apple devices drawback

This integration model has a drawback in Apple devices that also affects other providers and users. The HTML iFrame element, which is code used for the Appgree widget, is blocked by the Apple browser, regardless of the device used (computer, tablet or mobile). This blocks the automatic loading of the widget and requires an additional action from the user.

This behavior is based on the following security principle: in iFrame, content from domains not previously visited by the user cannot be loaded in another domain. This means that it’s only possible to load its content if the user has visited the site before.

¿How does Appgree solve this?

In a simple way, although it may be a bit cumbersome for the user. To prevent the user from arriving at a blank screen, Appgree asks the user to make two additional clicks, that is, instead of showing the content of the question directly (it would be blocked), a button appears. When clicked, this opens a new tab/window shows that directs the user to the site where the cookies need to be collected.

Once the button is clicked, a popup shows -like the one shown in this section- that enables the user to come back to the original screen. In this way, the user does not lose track of their navigation path.

When the button “OK” is pressed, the popup closes and the content shown before this last dialogue box refreshes. In this transition, the required messages are transferred, so that the original page can be viewed if the site visited complies with the security rules. Once this transition is over, the content of the question is automatically loaded so that this Apple drawback is resolved.

integra_appgree4biz_widget_6

integra_appgree4biz_widget_7

Integration in a page that is property of Appgree

This format allows users to view the widget in a page belonging to Appgree. The main characteristic of this solution is that it opens a tab/window through a URL where the previously mentioned values are specified, using a”QueryString”.

Let’s see an example URL (fake):

https://equipo.appgree.com/widget-pro-v1.html?email=1000001@equipo.com&firstName=Mario&lastName=Perez&attr1=attr1Value&attr2=attr2Value&apiKey=fbce6158527c18873da0ewrfsdf07950c8c9df5

The “widget-pro-v1.html” page would be provided by the Appgree team and would interpret the values specified in the “QueryString”, thus registering the user in the system and viewing the content of the website.

Where to integrate the widget

The Appgree team can help you find the most suitable placement for the widget. The idea is to make participating comfortable and simple for users, and Appgree will bring all its collective know-how and experience to bear to make it happen.

I’ve already integrated the widget, so now what?

Have you finished integrating the widget in different parts of your website or application? Now it’s time to get to the most important part of this integration: giving feedback to users.

Give feedback to users

Thanks to Appgree and the participants, you obtain truly valuable information for your organization. Appgree helps you create a community with your users as you get a dialogue going with them, but also helps you improve your services, products and business processes. This is the reason why you should never overlook the most important part: replying to users and giving them feedback on their ideas and concerns so they feel you listen to them and that their opinion matters. If you only put questions out and don’t take the time to explain why you are collecting their ideas, for example, they will feel as if they’ve been surveyed, and the conversation will only flow one way. Keep them informed of actions the organization is going to take based on their ideas, or at least thank them for their participation. If you don’t do this, they won’t feel engaged enough to keep on participating.

Recommended types of widget

Usually, we recommend using a Channel widget. This type of widget allows you to give feedback to the users in the same place where the questions are posted, through the creation of messages.

Otherwise, if you have selected a Channel history widget or a question widget, notice that these types of widget don’t show the messages created in the Channel. Therefore, if you decide to integrate one of these widgets, we would recommend creating a section in your website or application in which to give feedback to your users and keep them informed of the actions that have been taken thanks to their input in Appgree.

Utilizamos cookies y de terceros en la web para facilitar la navegación, recopilar estadísticas generales y mostrarle contenidos adaptados a sus intereses.

Ver política de Cookies ACEPTAR
Aviso de cookies