Best Practices
To ensure 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 ensuring 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, you 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 authorization. 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/authorize 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 authorization 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), as 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 ensure 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/authorization and launch the app configuration.

Submitting your app to the App Directory

When submitting your app, you will also need to provide information about your app to be shown in the App Directory.

We have specific recommendations for the content areas listed below.

Short Description

The Short Description is meant to be a brief one-liner about the app’s functionality. Please note that it should not be a tagline but rather a brief description of your app’s use case. For example, descriptions like "Enhance your marketing with MegaCorp’s Tools!" should be avoided, while ones like "Power your MegaCorp ad campaigns with targeted location data from Yext." are preferred.

Detailed Description

Your long description should be the single point of reference for anyone looking to learn more about your app. We require a few components in the description to make the listing as compelling as possible:
  • Detailed description on app functionality, especially with respect to Yext data
  • Step-by-step instructions for installing the app
  • Some basic information on what your product does
AVOID BRAND MARKETING We strongly discourage brand marketing in this section. Use the App Description to convey the specific app functionality only.
EXAMPLE Zendesk, Inc. builds software for better customer relationships. It empowers organizations to improve customer engagement and better understand their customers. Zendesk products are easy to use and implement. They give organizations the flexibility to move quickly, focus on innovation, and scale with their growth. Zendesk pulls all your customer information into one place, so you can track, prioritize, and solve customer support tickets with efficient, relevant, and personal communication. Take your customer support to the next level with the Zendesk For Reviews app.

With the Zendesk For Reviews app, you can optimize your customer support by streamlining workflows and leveraging customer information you already store in Zendesk with Yext. If you’re already using Yext Reviews to actively monitor your online reviews, you can see when customers express praise or criticism publicly via the reviews they leave on your website and sites across the PowerListingsⓇ Network. Set the Zendesk for Reviews app to generate a support ticket whenever you a receive customer feedback that you want to track.

The app allows you to create efficient internal workflows and resolve issues more quickly, so you can show all your customers that you care about their experiences:
  • Set review workflows to automatically generate a support ticket when a customer leaves a review of a particular rating anywhere in the PowerListingsⓇ Network
  • Assign reviews to different teams within your organization by setting filters of your choosing, including total rating, review content, and the location of the review itself
  • Ensure that appropriate action is taken quickly for each review, no matter the type of review
To install this app, you’ll need a Zendesk account with a subscription to the Team, Professional, Enterprise, or Elite plan. You will also be required to provide your Zendesk subdomain (e.g., yext.zendesk.com). Lastly, you’ll need a Yext account with a subscription to the Professional or Ultimate package.

App Icon

All apps within the Yext App Directory need a simple and memorable icon that attracts attention. Your icon is the first opportunity to communicate–at a glance–your app’s unique identity.

For more information, see Icon Guidelines.

Video URL

Though not required, we strongly encourage including a video that illustrates your app’s functionality and provides detailed installation instructions. App listings serve as an internal knowledge source for Yext sellers and Account Managers to help clients learn about and install apps. Accordingly, we have seen significantly higher adoption among apps that include videos in their listings. Including a Video URL will also significantly reduce the time your app is in review after you submit it.

Please note that we currently support only Vimeo video URLs.