The package allows you to bootstrap a React-based application, that's integrated with Zendesk App Framework(ZAF), and enables you to quickly get started with developing apps for Zendesk Sell.
Note: The docs are based on Zendesk Developer Guide. They contain only selected and hopefully the most necessary information in terms of creating an app integrated with Zendesk Sell. If you struggle with something or there's not enough information here, please visit the actual documentation.
The following folder structure and files must be included in an app to install the app successfully in a Zendesk product:
assets/
logo.png
logo-small.png
translations/
en.json
manifest.json
The following are brief descriptions of the required files:
Example HubSpot for Sell app manifest:
{
"name": "Hubspot",
"author": {
"name": "Zendesk",
"email": "[email protected]",
"url": "https://www.zendesk.com"
},
"defaultLocale": "en",
"private": false,
"singleInstall": true,
"location": {
"sell": {
"lead_card": {
"url": "assets/index.html"
},
"person_card": {
"url": "assets/index.html"
},
"company_card": {
"url": "assets/index.html"
}
}
},
"version": "2.0.3",
"frameworkVersion": "2.0",
"parameters": [
{
"name": "access_token",
"type": "oauth"
}
],
"oauth": {
"client_id": "{Client ID}",
"client_secret": "{Client Secret}",
"authorize_uri": "https://app.hubspot.com/oauth/authorize",
"access_token_uri": "https://api.hubapi.com/oauth/v1/token",
"scope": "contacts content oauth"
}
}You must declare where you want your app to appear in each product interface with the location property in manifest.json. The locations are where iframes can appear in the product.
You can specify one or more locations in one or more Zendesk products. By default your app will be available in Zendesk Sell on all object cards (Lead, Contact, Deal) in the panel on the right side.
"location": {
"sell": {
"lead_card": {
"url": "assets/index.html"
},
"person_card": {
"url": "assets/index.html"
},
"company_card": {
"url": "assets/index.html"
},
"deal_card": {
"url": "assets/index.html"
}
}
}For available locations, see Sell Apps API. To find out more about setting the app location visit Setting the app location section in the developer guide.
When an app makes AJAX requests, the settings for the request can be viewed in the browser console. Some settings may contain sensitive information such as an API key or token.
A recommended way to prevent this behaviour is to use OAuth Authentication. The other option can be using Secure Settings. Choose whatever option suits you best.
You can use OAuth2 to authenticate all your API requests to external service. OAuth provides a secure way for your application to access your account data without requiring sensitive information like usernames and passwords to be sent with the requests. To use OAuth authentication, you need to register your application with 3rd party service to generate OAuth credentials for your app. You also need to add some functionality to your application to implement an OAuth authorization flow.
When registering an app, you'll be presented with a screen showing the settings for your new app including the app name, the description, and other app information that you should fill in. In addition, you'll also find the Auth settings for your app such as the client ID, client secret, redirect URL, as well as the scopes used by your app. You'll need these items when initiating an OAuth connection between your app and 3rd party service.
Client ID - This ID is unique to your app and is used for initiating OAuth.Client secret - Used to establish and refresh OAuth authentication.Redirect URL - Users will be redirected to this location after granting access to your app.
Use one of the following urls:
Scope - Optional security measure. Scope determines what data your app has permission to access.OAuth URL - A user will need this URL to connect your app. The URL is being constructed based on your app's client credentials, redirect URL, and scopes configuration.Use the Client ID and the Client secret in your application as described in this following section.
Once you've registered your app you have to define OAuth settings in manifest.json file.
Update client_id and client_secret with yours.
"oauth": {
"client_id": "{Client ID}",
"client_secret": "{Client Secret}",
"authorize_uri": "https://app.hubspot.com/oauth/authorize",
"access_token_uri": "https://api.hubapi.com/oauth/v1/token",
"scope": "contacts content oauth"
}You also need to add a parameter of type "oauth" to the parameters list:
"parameters": [
{
"name": "access_token",
"type": "oauth"
}
]For more information visit the docs
In your app code, use the placeholder {{setting.access_token}} and a secure: true property to make an OAuth request.
var settings = {
url: 'https://www.example.com/api/user',
headers: {"Authorization": "Bearer {{setting.access_token}}"},
secure: true,
type: 'GET'
};
var client = ZAFClient.init();
client.request(settings).then(...);This is a JSON-only API. You must supply a Content-Type: application/json header on PUT and POST requests.
You must set an Accept: application/json header on all requests.
var settings = {
url: 'https://www.example.com/api/user',
dataType: 'json',
contentType: 'application/json',
...
};Secure settings are another way to make settings inaccessible to agents when making AJAX requests. The setting values are inserted only in the outbound request server-side at the proxy layer. See Using secure settings to set them up.
While you can use any custom CSS or front-end framework for the look and feel of your app, Zendesk recommends using Zendesk Garden. Zendesk Garden is designed to be a common baseline of styles and components between all Zendesk products. To make your app to match the Zendesk look and feel, Zendesk Garden is used in the app as a default.
Example:
.YourElement {
color: var(--zd-color-green-600);
padding: var(--zd-spacing-sm);
}For more information about the CSS classes and React components in Zendesk Garden, see garden.zendesk.com.
The ZAF client lets your app in the iframe communicate with the host Zendesk product. You can use the client in your apps to listen for events, invoke actions, and access properties in each location. See ZAF Client API guide.
Example:
const client = ZAFClient.init()
client.get('contact.email').then(function(data) {
console.log(data) // { "contact.email": "[email protected]" }
})@zendesk/sell-zaf-app-toolbox package delivers a bunch of useful methods, hooks and components that help you build React apps integrated with Zendesk Sell quicker and with less effort. They use Zendesk's App Framework Client under the hood. To find out more visit the repository.
Use your command-line interface navigate to the folder containing the app you want to test.
Install dependencies if necessary:
npm installStart your app with the following command:
npm startOpen a new window in your terminal and start the server:
npm run server
In a browser, navigate to the product page where you specified the app to appear (eq. deal/lead/contact card) and append ?zcli_apps=true to the URL. Example:
https://app.futuresimple.com/crm/contacts/1234?zcli_apps=true
In your browser's Address bar, click the shield icon on the right (Chrome) or lock icon on the left (Firefox) and agree to load an unsafe script (Chrome) or to disable protection (Firefox).
Note: Safari has no option to disable protection.
In order to lint and automatically fix some errors run:
npm run lintIn order to format your code:
npm run prettierBuild a package with minified sources:
npm run buildThe command creates a new .zip file in dist/tmp. Now your app is ready to be installed as a private app in your Zendesk Sell!
Integrations section and then select the Apps tab.Upload private app button.dist/tmp in your local app project.If your app uses OAuth or secure settings, you can keep testing it locally after installing it remotely.
zcli.apps.config.json
plan and paramters keys).{
"plan": "silver",
"app_id": YOUR_APP_ID,
"parameters": {}
}To find app installation id, sign in to your Zendesk Sell instance as an admin and open the following page in the same browser, replacing your_subdomain with your own:
https://your_subdomain.zendesk.com/api/sell/apps/installations.json (on production)
Locate your installed app and note its id value, not its app_id value.
