Best Practices
To guarantee a positive user experience– and to increase the likelihood of your app being approved for inclusion in the App Directory– we recommend that you follow the best practices outlined below.

More details about these best practices can be found in this site’s guides, but we’ve gathered them here for easy reference.

Designing your app

  • Yext customers are responsible both for making sure that data about their brand is correct and for leveraging that data within their role to deliver value to their businesses. As an app developer, you should keep this audience in mind for the Apps you create. In particular, your app’s use and installation should not require advanced technical knowledge or the involvement of multiple stakeholders.
  • Each app should perform only one key use case between the Yext Knowledge Engine and another external platform.
  • If you use Yext branding in your app, please adhere to our brand guidelines, as outlined on Brandfolder and make use of the assets provided there.

OAuth

  • We have implemented a standard OAuth 2.0 framework for authentication and authorisation. Redirecting to our OAuth flow allows us to securely authenticate with customers and prompt them to approve or reject the permissions your app requires. For more information, see OAuth and Permission Scopes.
  • On other platforms, we strongly recommend using an OAuth flow to authenticate/authorise the customer. If OAuth is not provided in the other platform, your app can request that the customer provide a static API key. This method is strongly discouraged, as it negatively impacts the customer experience and can give your app more permissions than it requires.
  • We recommend using a 470 x 600 pixel popup window to collect the customer’s authentication data.
  • Apps generally do not have a separate user datastore; we recommend using a unique account identifier from both Yext and the other platform to determine a user context. App configuration can be tied to that user context. With this method, if a customer presents authentication and authorisation for a matching Yext account and other platform account (regardless of the actual user credentials), they are presented with the same app configuration. To learn more, see Identifying Yext Objects.
  • Access tokens should be stored securely (e.g., encrypted at rest) because they are analogous to customer passwords. Never expose the access token outside of a secure connection with Yext during API calls.

Custom Fields

Your Custom Field Prefix should be a short, unique customer-facing string between 3 and 50 characters. This string will usually contain the name of the external platform your app is integrating with (e.g., "Zendesk", "Salesforce" or "HubSpot"). If your Custom Field Behavior is "Enabled for fields with prefix", all Custom Field definitions you manage in your app must start with this string.

Developing your app

  • Once your app is developed, we recommend testing your app thoroughly to guarantee an error-free customer experience.
  • Consider having your App Installation URL open a splash page that describes the app’s functionality before launching an OAuth flow.
  • Consider having your App Launch URL place customers directly into an OAuth flow to establish identity/authorisation and launch the app configuration.

Submitting your app to the App Directory

During the app-submission process, we strongly recommend that you provide a URL to video that illustrates your app’s functionality. Doing so will significantly reduce the time your app is in review.