Features

1. App Lifecycle Methods

2. Data Methods

3. Interface Methods

4. Request Methods

5. OAuth

App Lifecycle Methods:

window.app.initialized():

  The method is triggered when the page that contains the app is loaded for the first time. On success, it returns the client object. As the app renders within an IFrame, all communication (through Data methods, Interface methods, Events methods, Request methods) between the app and parent page occurs through the client object.

Sample client object initialization:

useEffect(() => {
  window.client = window.app.initialized();
}, []);

The object is loaded to the window object of the app.

Data Methods:

Currently the support is for only one data method which can be only used for the apps rendered on a survey’s integration page(builder_integrations_list). It can be used like:
window.client.data.get(“getSurveyId”)-> returns a long value

Interface Methods:

You can use the interface methods to trigger certain actions on the SurveySparrow user interface.

Success and failure toaster:

Once the client object is loaded to the window object of the app, then interface method for failure and success toastr can be used like:

window.client.interface.alertMessage(message, options); where message is a string and options is a object with key type and value with one of “success” or “failure”.

Sample:

window.client.interface.alertMessage("File upload failed", {
  type: "failure",
});

Request Method:

Request method is a secure mechanism to send HTTP requests from an app to a third-party domain, without exposing any sensitive information that is part of the request. Through browsers, app users may intercept sensitive information such as API keys or user credentials. Request method safeguards against such exposure. Typically, HTTP requests are routed through proxy servers. In such cases, sending the HTTP requests through the request method helps identify the origin in scenarios where the third-party domain has enabled Cross Origin Resource Sharing (CORS) support.

In this request method, the hosts to which the apps are expected to make request calls are whitelisted in manifest.json. The other attributes such as methods, paths, query parameters, header parameters, options, and request body are dynamically generated during runtime.

The request Method can be used like:

const response = await window.client.request.get(“URL”, options, params); const response = await window.client.request.post(“URL”, options, body); const response= await window.client.request.delete(“Url”, options, body); The response will be stringified to get the response in json format, it needs to be await json.parse(response);

As of now, get, post and delete request methods are supported.

Sample of request Method:

const domain = “https://api.surveysparrow.com”;

GET:

in app.js

const result = await window.client.request.get(`${domain}/v3/surveys`, {
     options: {
       headers: {
         Authorization: "Bearer <%=iparams.surveysparrow_api_key%>"
       }, isOAuth: false, maxAttempts: 5
     }
   });

in server.js

const result = await $Fetch.get(`${domain}/v3/surveys`, {
       headers: {
         Authorization: "Bearer <%=iparams.surveysparrow_api_key%>"
       }, isOAuth: false, maxAttempts: 5
  })

DELETE:

in app.js

 window.client.request.delete(
  `https://www.googleapis.com/calendar/v3/calendars/primary/events/${event.id}`,
  {
    options: {
      headers: {
        Authorization: "Bearer <%= access_token%> 
      },
      isOAuth: true,
      maxAttempts: 5,
    },
  }
);

POST:

in app.js

window.client.request.post("https://www.googleapis.com/calendar/v3/calendars/primary/events",
{options:
      {headers:{
         Authorization: "Bearer <%= access_token%> "
       },isOAuth:true,maxAttempts:5}},state)


The response body can be used like:
(JSON.parse(data).body)

in server.js

$Fetch.post("https://www.googleapis.com/calendar/v3/calendars/primary/events",state,
  {
        headers:{
         Authorization: "Bearer <%= access_token%> "
       },isOAuth:true,maxAttempts:5
  });

Status Codes:

OAuth:

You can use the OAuth 2 protocol to authorize an app to access resources from third-party applications. This is done by using an access token obtained from the third-party when the app is installed.

• Register your app in the third-party AppNest. Once registered, you will be issued with client_id and client_secret to perform OAuth handshake with the provider.

• Provide the redirect URL for your app in the third-party AppNest.

   1. Testing:https://localhost:30001/auth/callback?callback=https://localhost:30001/custom_configs?product=surveysparrow&product=surveysparrow(the product should be the name of the environment you are testing)

   2. Production: https://marketplace.surveysparrow.com/api/marketplace-redirect-url

Note: while testing the app, the scopes should be given inside options but in production the scopes should be given seperately as scopes.

The access token and refresh token are stored and maintained by the AppNest itself and to use them in the request method’s url and options like: <%=access_token%>.

Sample:

in app.js

window.client.request.post("https://www.googleapis.com/calendar/v3/calendars/primary/events",{
  options:{
    headers:{
         Authorization: "Bearer <%=access_token>"
       },isOAuth:true,maxAttempts:5
      }
  },state);

in server.js

$Fetch.post("https://www.googleapis.com/calendar/v3/calendars/primary/events",state,{
    headers:{
         Authorization: "Bearer <%=access_token>"
       },isOAuth:true,maxAttempts:5
  })