Skip to main content Link Menu Expand (external link) Document Search Copy Copied

Features

1. App Lifecycle Methods

2. Data Methods

3. Interface Methods

4. Request Methods

5. OAuth

6. Iparams

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 an 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 received will be stringified. To get the response in JSON format, use 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:

app.js

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

server.js

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

DELETE:

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:

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}},payload)


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

server.js

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

Status Codes:

Code Description
400 Is returned due to invalid input. For example, if you are making a request to a domain that has not been whitelisted or if the request is passing secure iparams in the body or URL, you will receive this status.
401 Is returned if you performed an unauthorized request.
429 Is returned when the number of requests exceeds the threshold.
500 Is returned if the server encountered an unexpected error.
502 Is returned when there is a network error.
503 Is returned when the service is temporarily unavailable.
504 Is returned when there is a timeout error while processing the request.

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(the product should be the name of the environment you are testing)

   2. Production:

   For US region:https://marketplace.surveysparrow.com/api/marketplace-redirect-url

   For EU region: https://marketplace-eu-ff.surveysparrow.com/api/marketplace-redirect-url

Important: To configure third-party OAuth, create a file named oauth_config.json in the config folder and add the below key-value pairs.


FIELD DESCRIPTION
client_id
Mandatory
Once you register your app in the third-party AppNest, you will be issued a client ID for your app.
client_secret
Mandatory
Once you register your app in the third-party AppNest, you will be issued a client secret for your app.
authorize_url
Mandatory
Third-party authorization request URL.
token_url
Mandatory
Request URL for the access token.
options The options field can be used to send:
- Additional parameters to the resource owner while fetching the access token. Custom headers as part of the token phase as required by certain third-party services. For this, custom headers can be included in the options field as an object.
"customHeaders": { "Authorization" : "Basic API_KEY" }
provider is a part of options which should be one of google, slack, notion or twitter "provider":"twitter"
scopes
(Mandatory only when the app is published in production account. Otherwise the scopes can be added as scope array inside options for local testing)
To control the level of access on the resource. It should be array of strings

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

Sample payload:

{  	
"client_id":"Your-client-id",
"client_secret":"your-client-secret",
"authorize_url":"your-authorize-url",
"token_url":"your-token-url",
"token_type":"account",
"options":{
  "response_type":"code",
  "access_type":"offline",
  "prompt":"consent",
  "scope":["https://www.googleapis.com/auth/contacts"]
  }
}

The access token and refresh token are stored and maintained in the AppNest. You can add the access token to the request method’s URL and options as <%=access_token%>.

Sample:

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
      }
  },payload);

server.js

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

Iparams:

In the code logic Iparams can be fetched using the iparams method. In some cases the iparams will be required inside the code logic rather than only in the API calls.

For this use,

  1. client.iparams.get()
  2. client.iparams.get(iparam_key)

sample:

app.js

try {
  const installed_parameters = await client.iparams.get();
} catch (error) {
  console.error("Problem with retrieving Installation Parameters", error);
}

server.js

try {
  const installed_parameters = await $Iparams.get();;
} catch (error) {
  console.error("Problem with retrieving Installation Parameters", error);
}

sample response:

{
  "surveysparrow_api_key":"dfghj",
  "name":"asasas"
}

Fetching Iparams for a specific key:

sample:

app.js

try {
  const installed_parameters = await client.iparams.get("surveysparrow_api_key");
} catch (error) {
  console.error("Problem with retrieving Installation Parameters", error);
}

server.js

try {
  const installed_parameters = await $Iparams.get("surveysparrow_api_key");;
} catch (error) {
  console.error("Problem with retrieving Installation Parameters", error);
}

sample response:

{
  "surveysparrow_api_key":"dfghj"
}