For partners: How to integrate with Judge.me

TABLE OF CONTENTS

• 1. How to integrate with Judge.me
  • 1.1. For integrations done by Judge.me
  • 1.2. For integration done by the partners
    • Step 1: Check our documentation
    • Step 2: Fill in the pre-integration form
    • Step 3: Start building the integration
    • Step 4: Test the integration
• 2. Co-marketing activities
• 3. Some integration tips for specific apps
  • 2.1. For email, SMS and push notifications apps
  • 2.2. For product recommendations and upselling, search apps and page builders
  • 2.3. For loyalty/rewards and storefront notifications apps
  • 2.4. For SEO apps
  • 2.5. For shipment tracking apps
  • 2.6. For translation apps

For technology partners to integrate with Judge.me, there are three cases:

• Judge.me build the integration from our side. In this case, we need to determine the conditions within our system before making an API request to the partner’s server with relevant data.
• The partners build the integration from their side with available resources, without Judge.me involved in the process. Integration that only requires access to public data such as our cache server can use the method.
• The partners build the integration from their side with available resources but need verification from Judge.me about the permissions they can use. Integration that requires access to the store’s private data needs to use this method. For security reasons, we strongly recommend that all partners build the integration using the OAuth approach, and request access to only necessary data. Otherwise, we can't verify and promote your integration officially.

Here is the list of common apps and how they integrate with Judge.me:

1. How to integrate with Judge.me

1.1. For integrations done by Judge.me

• If you have an integration idea and that integration needs to be done by Judge.me, please contact partnerships@judge.me, and provide us with:
  • Use cases of the integration you want us to build, as well as links/resources to similar integrations if any.
  • Your API documentation, integration guidelines, FAQ, etc.
  • Any information you need from us before we start building the integration?

• After getting documentation, we’ll research and discuss internally how to implement the integration. Then, we may exchange emails or schedule calls to discuss and confirm the integration approach. 
• After the integration is completed, we can provide you with testing instructions upon request, and start doing co-marketing activities to promote the integration.

1.2. For integration done by the partners

If the integration needs to be done from your side, we’ll follow these steps:

Step 1: Check our documentation

• To get started, please check our public API documentation and guides about the APIs and how to make advanced customizations.
• Judge.me uses OAuth to grant you access to our API. You should request only the relevant permissions so you are more likely to get approval from the users (stores). Learn how to set up OAuth in Judge.me.
• If you have any questions, check our FAQ or contact us via partnerships@judge.me.

Step 2: Fill in the pre-integration form

• To help us understand more about the integration you are building, please duplicate and fill in this pre-integration form on Google drive:
  • A description of the feature(s) that you are going to build, and how the feature(s) can add value to users from both sides. 
  • What data/access do you need from Judge.me? A brief reason for each permission
  • Which e-commerce platforms will your integration be available on? (Shopify, WooCommerce, BigCommerce, Squarespace)
  • Which pricing plan(s) of your app will the integration be available on?
  • The contact person on both the technical and marketing sides.
  • Rough ETA of the integration.
• After you fill in the form, we’ll contact you within 1 week to confirm your request.

Step 3: Start building the integration

• After your integration request is confirmed, you can start building the integration. 
• You can install Judge.me on your development store and upgrade to our Awesome plan for free. With our Awesome plan, you will have access to all our features. 
  • If you are a Shopify app provider, please create a Shopify development store to upgrade to our Awesome plan for free. 
  • If you are on WooCommerce or BigCommerce, all stores are automatically on the Awesome plan for free at the moment.
  • If you are on Squarespace, please contact us at partnerships@judge.me and we’ll grant free access to your test store.
• If you have any technical questions, please send an email to partnerships@judge.me. If necessary, include a screencast of steps to reproduce the issues.
• The co-marketing activities can only start after the integration is tested and verified by Judge.me. Therefore, we expect that you:
  • Announce to us when the integration is done before doing any promotion on your side.
  • Provide clear testing instructions, and the expected outcomes (the features), so we can have a quick test to verify the integration.
  • Can handle the support tickets coming from your side.

Step 4: Test the integration

After finishing the integration, please duplicate and fill in this QA testing form that includes:

• A description of the integration (the features and the expected outcome of the whole integration)
• Step-by-step instructions:
  • For each step, ideally, include a screenshot of the instructions and the corresponding expected outcome. You can also include a single demo video for all steps.
  • The clearer the instructions are, the faster Judge.me can verify the integration and promote your integration.
• Login access to the integration:
  • Provide the credentials to access your test store or,
  • Grant free access to Judge.me’s test store

2. Co-marketing activities

After we finish testing and verifying the integration, we'll move forward with co-marketing activities, please find more details here.

3. Some integration tips for specific apps

In the following sections, we outline some tips and address common questions for specific types of apps:

2.1. For email, SMS and push notifications apps

• Integrations with email, SMS, or push notification apps will be done from Judge.me’s side. 
• Specifically, we will make an API request to your server to send an email, SMS message, or push notification with the content and recipient of the review request. Therefore, please contact partnerships@judge.me for more details.

2.2. For product recommendations and upselling, search apps and page builders

• If you want to display Judge.me widget information (stars, aggregate ratings, review count, carousel, specific product reviews, etc.) as part of your own widget appearing on the merchant’s front end, we recommend you use the cached version of the Judge.me widgets by making a request to our cache server. It’s not only faster than using Judge.me API but also allows multiple widgets to be loaded in a single request. Check this FAQ to see an example of how to get the aggregate ratings using our cache server. The cached server is public data so you don’t need to request permission via OAuth.
• If you want to build your own HTML, you should fetch the aggregate_feed from us and build the badges (stars) on your server. However, our aggregate_feed is a feature on our Awesome plan, so if you follow this approach, your integration will only be available to Awesome users.
• If you want to get review count and rating per product for some products, on the fly, using JS running on browsers, you can use jdgm.batchRenderBadgesWithCallback following this guide.

2.3. For loyalty/rewards and storefront notifications apps

If you want to get our review information to perform a specific action, you can create webhooks on your side to pull information from us. To build this integration, you’ll need to request permission following our OAuth process.

• For loyalty/reward apps: When a new review is submitted, we will check whether the shop enables reward integration or not.
  • If the shop doesn’t enable any integration, we'll use our internal coupon system.
  • If the shop enables one integration, we check which reward integration they are using and send review information to the reward app’s system.
• For storefront notification apps: When a new review is submitted, we will notify the partner’s app to display a storefront notification of the new review.

2.4. For SEO apps

• If you want to get our schema markup to display product reviews in rich snippets, please add these three lines of code in the products' snippet (the #product after @id is optional).

{%- if product.metafields.judgeme -%}

"@id": {{ canonical_url | append: '#product' | json }},

{%- endif -%}

• In general, your JSON-LD script needs to have an @id. Our app will detect the @id of your script and replicate it to merge our AggregateRating with the rest of your script. The integration will link your JSON-LD product snippets with our JSON-LD review snippets, helping your users to show ratings in organic search.

2.5. For shipment tracking apps

• If you are a shipment tracking app, you can allow merchants to send review requests based on order delivery dates (instead of order fulfillment dates) by updating the delivery status directly to Shopify. 
• After the users install your tracking app and enable the Delivery-based requests in Judge.me, we will schedule review requests when the order is updated as “Delivered” in Shopify. At the moment, we prefer this method and once you update to Shopify, other apps can also use this data.

2.6. For translation apps

• We already pushed our own translations to Shopify for widgets texts, so integration with a translation app is normally not required anymore (i.e. translation within Shopify secondary languages via translatable resources). The only exception is an integration that provides translations of the page content on the fly like Weglot, and translations out of Shopify secondary languages.
• We also don't encourage you to modify/translate our Shopify metafields (any metafield containing "judgeme"), because:
  • Those metafields contain HTML code and it's fairly easy to break them by accident, which means breaking the store pages
  • We update the content of those metafields every time there is a change in our system. So the translations would have to be updated every time there is a change in the metafield.