When you build an app for Hygraph, you must register it in Hygraph Studio.
Apps will not work on your local environment because our SDK only runs inside our platform.
To register your application, you first need to navigate to Your apps. You can access it from your user settings or from the project directory.
To find it in your user settings, navigate to User settings > Your apps.
Your apps in user settings
To find it in your project directory, click the Your apps tab at the top of the screen.
Your apps in project directory
Click + Add new app to open the App registration form.
The registration form is divided into four tabs:
App registration form
You will be able to save your app by clicking on the Register app button, as long as you provide information in the required fields.
When you create your own app, click Register app only at the end of the process as some information - such as permissions - can't be edited after the initial save.
#General
App registration - General
- Name: Mandatory field. This is the name of your app.
- Description: Optional field. Here you can provide a description for what your app does.
- Avatar URL: Mandatory field. The avatar URL is the logo that will display next to your app's name. Provide a URL that indicates where your logo is hosted.
- API ID: Mandatory field. This is where you write your API ID. The form will let you know if the name is taken. This field only allows alphanumeric characters, underscores and hyphens, and you must start with a lowercase letter. This field becomes read-only once the app is created, and you cannot modify it. API IDs are unique across all applications.
- Setup URL: Mandatory field. The setup URL provides the form that displays to users when they install your app for the first time in Hygraph. The form will require some information from the user depending on the characteristics of the app.
Once you've completed all mandatory information, you can move on to the next tab.
#Permissions
This section shows the access details of your app.
App registration - API and Installation permissions
Setting up your app permissions incorrectly might cause the app to not work when installed.
API permissions are only editable when first creating the app. Once the app has been saved for the first time, they can't be changed.
-
API Permissions: Use these dropdown menus to select permissions for Content API, Schema, Webhooks, and User.
- Content API: Grants the app permissions regarding the content. For example, a localization app would need
read permissions to access the content to be submitted, then also write permissions to allow the content to be translated.
- Schema: Grants the app permissions regarding the schema of your project. For example, an app that sets up models in your schema which will be ready to be used after the app installation, would need
read / write permissions.
- Webhooks: Grants the app permissions regarding your project's webhooks. For example, a newsletter app which sets up a webhook during installation that can later be triggered upon a certain action, would require
read / write permissions.
- User: Grants the permission to read the user ID and their roles and permissions to implement access control features within the app.
-
Installation permissions: These permissions impact who can access the app. You can use the App access dropdown to make the app private or shared. If you select Private, then you can click + Add member below to add a member, or + Add project to add a project. The selected members/projects will be able to install the app.
-
Regenerate Client ID and Client secret: The Client ID and Client secret are the credentials that allow apps to perform actions on behalf of the user. If you lose or forget them, you can regenerate them after creating the app.
- Client ID: Unique identifier of your app that is used for authentication and authorization. Your Client ID will only display after the app has been saved for the first time.
- Client Secret: Used with the Client ID to resolve and grant access to your app. Your Client Secret will only display after the app has been saved for the first time.
Regenerate Client ID and Client Secret
- Transfer app ownership: An app can only be owned by one person at a time. App owners can hand over ownership to someone else if they won't be able to manage the app anymore. To transfer ownership, click Transfer ownership, and provide the email address of the new owner. The new owner receives an email with a confirmation link. As soon as they confirm, the ownership is transferred.
Transfer app ownership
#Elements
App registration - Elements
The Elements section will require different data depending on the element type you select. To start adding elements, click on + Add element:
- Name: This is where you write the name of your element.
- API ID: This is where you write your element's API ID.
- Type: when you create an app, you can have field elements, sidebar elements, or pages.
field: Field elements are custom fields that you can add to a model's fields schema.formSidebar: Sidebar elements are custom widgets that you can add to a model's sidebar schema.page: Page adds a section for the app under App views in the Content editor.
- Features: This dropdown only displays when
field is selected as type, and allows you to select features for said field. One or more features can be selected using the dropdown:
FieldRenderer: If the feature contains this, it can be rendered for fields.ListRenderer: If the feature contains this, it can be rendered for LIST fields. Click here to learn more about how it works.TableRenderer: If the feature contains this, it can be rendered for Table Cell. Click here to learn more about how it works.
- Field type: This dropdown only displays when
field is selected as type . It allows you to select how the data will be stored, by selecting one of the standard field types from the dropdown menu.
- URL: Indicates where this element is located in the project, its dedicated URL.
- Description: It's the description that will appear under your field name in the Add Field / Sidebar Widgets section of the Schema.
- Config: You can have custom settings for elements. This field is completed using a
JSON object, which is used to declare extra fields the user wants to render in the field or sidebar form.
- Click here for detailed information on field configuration.
- Click here for detailed information on sidebar configuration.
#Sharing
App sharing enables other users to install your app.
App registration - Sharing
After creating an app and saving it for the first time, this section will show the App Sharing read-only field, which contains the URL that you can copy to then share your app.
Alternatively - after the initial save of your app - you can share it by navigating to User Settings > Your Apps, locating the card of the app you wish to share, and selecting the Share app option that you'll find in the context menu.
#Registration
You can save your app by clicking on the Register app button, as long as you provide information in the required fields. We recommend you to click Register app only at the end of the process as some information - such as permissions - can't be edited after the initial save.
After you register your app for the first time, the client ID and client secret will be available on the Permissions tab of the app.
- Client ID: Unique identifier of your app that is used for authentication and authorization. Your
Client ID will only display after the app has been saved for the first time.
- Client Secret: Used with the Client ID to resolve and grant access to your app. Your
Client Secret will only display after the app has been saved for the first time.
The Client ID and Client secret are the credentials that allow apps to perform actions on behalf of the user.
If you lose or forget them, you will have the option to regenerate them after app creation.
Regenerate Client ID and Client Secret
#Installation
After you've successfully created an app, you will need to install it in order to be able to use it. This guide contains step-by-step information on how to do this.
#Resources
- App Framework: Overview to our App Framework, which extends Hygraph capabilities, offering the possibility of creating your own custom apps and sharing them with other users.
- Migrate to apps: A guide on migrating from UIX to app.
- Using app tokens: Document on how to generate an app token for your app during installation.
- Install an app: Step by step guide on how to install an app in your Hygraph project.
- Delete an app: Documentation for developers on how to delete an app you have created.
- First steps: This is our App Framework tutorial, a comprehensive step-by-step guide on how to develop an app with custom field and sidebar elements.
- Next.js starter: Document that guides you through the process of developing an app with a custom field using our
Next.js starter.
- API Reference: Our App Framework API Reference.