Custom Integrations (Petfinder App)

This tutorial covers how to build an app that facilitates pet adoption through a custom integration with the open-source API, Petfinder. Check out this tutorial if you want to learn more about:

• Creating custom integrations

• Querying external APIs

• Working with data pulled from external sources

• Displaying repeating elements

🚧 This is an advanced tutorial. It assumes comfort working with external integrations and HTTP requests, as well as familiarity with the contents of the tutorial, Your First App (A Simple Form). If you haven't gone through that tutorial yet, we recommend you do so before proceeding.

Here are the parts of the Airkit platform that you will be working with:

• Console: Configuring your integration

• Settings: Tying the integration to the Journey

• Web Flows Builder: Creating the UI

• Connections Builder: Querying the API and reformatting the data

• Media Library: Uploading pictures to display in the UI

• Variable Tree: Manage local variables

For a demonstration how this application will work once we're finished, check out this video:

[block:embed] { "html": "<iframe class="embedly-embed" src="//cdn.embedly.com/widgets/media.html?src=https%3A%2F%2Fwww.youtube.com%2Fembed%2FEs_SGNu9dt4%3Ffeature%3Doembed&display_name=YouTube&url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DEs_SGNu9dt4&image=https%3A%2F%2Fi.ytimg.com%2Fvi%2FEs_SGNu9dt4%2Fhqdefault.jpg&key=f2aa6fc3595946d0afc3d76cbbd25dc3&type=text%2Fhtml&schema=youtube" width="854" height="480" scrolling="no" title="YouTube embed" frameborder="0" allow="autoplay; fullscreen" allowfullscreen="true">", "url": "https://www.youtube.com/watch?v=Es_SGNu9dt4&feature=youtu.be", "title": "Petfinder Tutorial - DEMO", "favicon": "https://www.youtube.com/s/desktop/d4eb50c8/img/favicon.ico", "image": "https://i.ytimg.com/vi/Es_SGNu9dt4/hqdefault.jpg", "provider": "youtube.com", "href": "https://www.youtube.com/watch?v=Es_SGNu9dt4&feature=youtu.be" } [/block]

You will also be creating a free account with https://www.petfinder.com/ as part of the process of integrating with their Petfinder API.

Creating a Web Flow

When creating an app, you will first land on Web Flows Builder in the Studio. This is where you'll design and build the front-end experiences of your app.

To do so, click on Create blank Web Flow:

Setting up the Petfinder API

To integrate with the Petfinder API, you need to register an application and obtain the API key and Secret. To get an API key, you need to create a Petfinder account.

1. Create an account at https://www.petfinder.com/user/login/

2. Once logged in, go to www.petfinder.com/developers and complete the form with your app details.

3. Finally, click on Get a key.

Now your API Key and Secret are ready to be used to integrate your Petfinder account with your app.

Creating the Custom Integration

Now that you have the API Key and Secret, go back to the Console to establish your custom integration. We recommend doing so while keeping Petfinder's reference documentation open, to keep the configuration details handy.

Why does the integration process require leaving the Studio and making changes in the Console?

Keeping track of integration credentials is done at the Org-level rather than within individual applications. Once a resource has been established, it can be used in all applications within the Organization.

This saves time in the long run: integrations only need to be established once, and the inherent standardization of the connections makes it easier to use external tools as a single source of truth within multiple Airkit apps.

1. Click on Integrations on the left side menu. Select Custom Integrations and click on Create new.

1. A few fields will display for you to complete as follows:

   • Designate your integration with an intuitive name, such as "Petfinder integration".

   • Enter “petfinder-integration” under Key. This will be used to identify the integration.

   • Select Custom Token as the Authentication Type.

   • Under Access Token Endpoint, enter the following URL from Petfinder's API reference docs: https://api.petfinder.com/v2/oauth2/token

   • Select POST under the Access Token Verb.

1. Under Access Token Parameters, click on the ‘+’ icon to define the following integration parameters:

   • grant_type:

• Client_id (Set the Parameter Value to the API Key associated with your Petfinder Account):

• Client_secret (Set the Parameter Value to the Secret Key associated with your Petfinder Account)):

1. Once the Parameters are set, complete these last three fields:

   • Choose Header as the Token Parameter Type.

   • Name the Token Parameter “Authorization”.

   • Enter "Bearer {token}" as the Parameter Value and click the Create button.

Now you can see Petfinder listed among your custom integrations.

Creating a Connected Account

After setting up the custom integration, you need to connect the integration to Airkit. This will surface the integration to your application and make it usable in apps.

1. Go Integrations > Connected Accounts and click on Create new. Define an intuitive account name (such as "Petfinder Integration") and select the Petfinder integration from the integration’s dropdown.

1. Click on Create to connect the integration. It will show up in the list among your other connected accounts.

Connecting the Petfinder Integration to the Application

Once an integration with Petfinder has been established at the Org-level, re-open your pet adoption app in the Studio and toggle over to Settings.

1. Once in Settings, locate the Integrations section.

2. Click on the ‘+’ icon and select the Petfinder Integration as the adapater.

1. Under Connected Account, select the Petfinder Integration.

You've now integrated your pet adoption app with the Petfinder API! Save your progress, and get ready to incorporate some HTTP requests to the Petfinder API into your application flow.