How to create your first Safari Extension Manifest V3?

Introduction

In this developer article, I will guide you through the complete process, starting from writing code to publishing the Safari Extension Manifest V3. These steps cover everything, from xCode and AppStoreConnect to earning revenue through downloads on the App Store (both Mac and iOS App Store). Keep in mind that Safari extension development is exclusive to Mac users, and Xcode is a prerequisite for the process. Unfortunately, there is no solution for Windows users, as the Safari desktop web browser is only compatible with the Apple ecosystem.

The development process follows the Traditional Waterfall Approach system, encompassing preparation, coding, testing, documentation, and maintenance.

Additionally, I will discuss 10 crucial points that could hinder the successful submission of your first Safari extension to the App Store. Given the Apple ecosystem’s constraints, it is essential to adhere to Apple product list limitations when publishing your extension.

Preparing to create Safari Extension Manifest V3

Register App ID

1. To access the App Store Connection, new developers are required to pay a yearly fee of 99 USD or 99 euros. This payment grants you entry to the portal, enabling the publication of apps on the App Store. Refer to this helpful page for guidance on enrolling in the Apple Developer Program subscription service and gaining access to the App Store Connect page.
   (Before 2011, Apple had a free Safari program for publishing Safari extensions. However, this program was deprecated in 2015.)

2. Click on the blue circle with the plus icon to initiate the creation of a new application. Then, select the menu item “New App” to begin the process of obtaining your first Safari Extension Manifest V3 in the store.

3. A new modal will appear. Before filling in these input boxes, you need to create your app ID first. Click on the blue hyperlink “Certificates, Identifiers & Profiles“. Once on that page, enter your application name in the description box and the bundle ID in reverse domain, like “com.stefanvd.print-for-safari“. Afterward, click on the blue “Continue” button.

4. Once everything is in order, proceed by clicking the blue “Register” button.

5. Now, on the “New App” modal, input your app name, select the primary language (e.g., English (U.S.)), and enter the newly created “Bundle ID”. Provide an SKU name to locally identify your application; for instance, use “stefanvd-printforsafari” following the format (author – product name). Lastly, set “User Access” to “Full Access” to ensure you have complete control for any changes or updates.

Manage New App (with Safari Extension Manifest V3)

Now, you will be directed to the homepage, where you can manage your description and screenshots for each platform (Mac and iOS).

Here, you can upload screenshots for your Safari Extension Manifest V3 on both the Mac and iOS apps. Include the necessary description text, keywords, and the product marketing URL to provide more information about your Safari extension.

App Information

1. Now, let us update the App Information tab. Click on this tab in the left-side panel and open “Content Rights”. A modal will appear. In this modal, select the radio button “No” if you are not using any other third-party content. Then, click on the blue “Done” button to confirm and close the modal.

2. Next, click on the button to add the “Age Rating”. In this modal, select the option that corresponds to your newly created account. Once done, click on the next button.

3. In section 2, choose “No” as it is a Safari Extension Manifest V3 and not a web browser. Additionally, select “No” as it is not a gambling application.

4. Now, you will see the result of your rating. To save it, click on the blue “Done” button.

App Pricing and availability

Now, we are going to set the price for your Safari Extension Manifest V3 and determine its visibility worldwide. Click on the first blue button, “Add Pricing”.

Pricing

1. A new App Pricing modal will appear. In the price selection box, choose your price for your Safari Extension Manifest V3. I selected $0.00 as my browser extension is free and Open-Source for all web browsers.

2. On the next page, choose the country or region to adjust the price. Since it is free, no adjustment is needed, and you can click on the blue “Next” button.

3. Review the final result and click on the blue “Confirm” button to close this modal.

App Availability

1. Now, click on the “App Availability” button to select where the app should be visible.

2. Choose the radio button “All countries or Regions”. Click the blue “Next” button.
3. Now click on the blue “Confirm” button to close the modal.

App Privacy

Now, the final step is to address your application’s privacy. Initially, you will see a blank privacy URL. Click on the blue “Get Started” button to add your privacy page.

1. A new Data Collection modal will appear. Choose the radio button indicating that you do not collect data in this app. Then, click on the blue “Save” button.

2. Now, on this screen, enter your Privacy Policy URL and click on the blue “Save” button.

3. Now, you will see the privacy badge labeled “Data Not Collected,” which will be visible in the App Store.

4. If you agree, now click on the blue “Publish” button.

Coding

Now, let us move on to the code development work. If you already have a successful Chrome extension with Manifest V3 in the store, ensure that you have the zip file from your working Chrome extension and place it on your desktop. Unzip the file to a folder.

While you can use Manifest V2, it is advisable to use Manifest V3 for uniformity across all web browsers and to leverage the latest advancements in performance, security, and privacy technology for your users.

Requirement:

• Make sure you have installed Xcode 15.1 on your Mac computer
• You are using the latest macOS 14
• Chrome Extension folder

The converter will perform the following tasks:

• Creates an Xcode project
• Configures the Xcode project with a macOS app or iOS app that installs the extension in Safari
• Configures a Safari web extension with your extension files in the Xcode project

Follow the steps here below on how to get your Xcode project for your Safari extension:

1. Open the Terminal that can be found in the Launchpad
2. When the Terminal window is open execute this path in your Terminal

xcrun safari-web-extension-converter /path/to/extension

3. It creates a complete Xcode project. That includes the app on macOS and iOS and the shared folder that contains your new Safari extension.

That is it. It has created a new folder “Print for Safari” on the desktop. Open this folder, and you can access the “Print for Safari.xcodeproj” Xcode project. Now, you can run and test your Safari Extension Manifest V3 on desktop and mobile, including your iPhone and iPad.

However, there are some improvements needed:

• Here, it uses a different bundle ID
• The app category is not selected
• The manifest.json specifies that only a certain version of the Safari extension can run this. Note that Safari 15.4 only supports Safari Extension Manifest v3.

"browser_specific_settings": {
"safari": { "strict_min_version": "15.4", "strict_max_version": "*" }
}

• Also, ensure that your translation name does not exceed 112 characters, as this could lead to a failure during the App Store submission later on.

Asset validation failed
Invalid messages file. The messages.json validation failed for locale ar in the Safari web extension bundle Print for Safari.app/Contents/PlugIns/Print for Safari Extension.appex. The description field must be present, of string type, and 112 or fewer characters long.

Testing

Device

Make sure to test your new Safari Extension Manifest V3 on a real device, not in a simulator, such as a MacBook or an iPhone 15 device. Test it from a user’s perspective to identify and address any potential pain points.

Select in the Xcode toolbar the platform you want to test your new Safari Extension Manifest V3. For example “Mac”. Click on the play button left of this selected platform.

App Store Guidelines Compliance

Ensure your extension complies with Apple’s App Store guidelines to avoid rejection or removal.

If you are a beginner developer, follow these guidelines because failing to adhere to the Apple Store Guidelines can prevent your new Safari Extension Manifest V3 from becoming visible in the App Store. Here are 10 important guidelines that you may overlook when publishing in a store that is more relaxed in terms of openness and freedom for the user:

1. Make sure that the features mentioned in the App Store description text are already present in the Safari extension and not just promised as “coming soon”. It is not permitted to write about features that are not currently available in your Safari extension, as Apple may disallow the app from the App Store in such cases.
   See 2.1 App Completeness
2. You are not allowed to include a PayPal or any donation link in your Safari extension. If you wish to receive donations for your free Safari extension, you must utilize Apple’s in-app purchase API.
   See 3.1.1 In-App Purchase
3. If your Safari extension is part of an online subscription service, you are required to provide Apple’s in-app purchase API as an option.
   See 3.1.2 Subscriptions
4. Ensure that the Safari extension offers sufficient complexity for the user. A single action with no customization is not permitted on the App Store. Provide a variety of customization options for Safari users.
   See 4.2 Minimum Functionality
5. Your Safari extension must function with the latest version of Safari on both Mac and iPhone. Additionally, it should include settings and a help screen to guide users on how to set it up.
   See 4.4 Extensions
6. When creating a screenshot of your Safari extension for the App Store, ensure that no third-party applications are visible. This means excluding any other web browser applications, such as Google Chrome, and avoiding the display of unrelated applications like Visual Studio Code. Additionally, refrain from using screenshots featuring the Google Chrome logo.
   See 3.2.2 Unacceptable
7. In the App Store description text, refrain from mentioning support for other web browser names, including Google Chrome, Firefox, Opera, and Microsoft Edge.
   See 3.2.2 Unacceptable
8. When naming an application on the App Store, avoid using the name “XXX Safari.” Instead, use the name format such as “XXX for Safari”.
   See 4.1 Copycats
9. Ensure that you have a working privacy page for both your app and Safari extension. It should be visible to new users on the App Store.
   See 5.1 Privacy
10. Avoid using trademarks in your application name. It is prohibited to use them as part of your new application name. For instance, do not use names like “YouTube XXX.”
    See 5.2 Intellectual Property

Publication

Certificate

Ensure that you have all five certificates installed. That is needed to sign your Mac and iOS application (that includes your Safari Extension Manifest V3) to publish it in the App Store:

• Apple Development: Stefan Van Damme
• Developer ID Installer: Stefan Van Damme
• Apple Distribution: Stefan Van Damme
• 3rd Party Mac Developer Installer: Stefan Van Damme
• Developer ID Application: Stefan Van Damme

To check if you have those certificates installed on your device, use the following Terminal command:

 security find-identity -v

To create a developer certificate see this Apple developer help page.

Archive it

Now, we are going to archive the file so you can upload it to the App Store. Here are the steps:

1. Ensure you select “Mac application” and “Apple Silicon, Intel” (as indicated by the red rectangle).

2. Now, open the “Product” menu from the Apple menu bar, and then click on “Archive”.

3. A new window will appear; click on the blue button “Distribute App”.

Next, click on “TestFlight & App Store”, then click on the blue button “Distribute”. It will automatically package, sign, and upload to the store.

App Store Connect

Now, open your App Store Connect for your new app, named “Print for Safari.” Click on the button. On the “Prepare for submission” page, scroll down to the “Build” section. Here, you can choose the latest uploaded archive file.

When everything is complete, click on the blue button “Add to Review” at the top of the webpage.

App Store Connect

Everything you need to publish is available with App Store Connect. To make the Safari Extension Manifest V3 available, you need to pay a yearly fee of 99 USD or 99 euros to keep it visible in the App Store.

Having a paid Apple Developer account comes with several benefits, especially if you are an app developer or interested in creating software for Apple’s platforms. Here are some of the key advantages:

• Two technical support assistants to help with your code.
• Access to WWDC each year, where you can ask your developer questions to an Apple engineer via a Webex meeting call from Apple Inc. in Cupertino, California, United States.
• Ability to test the latest developer versions of macOS, iOS, iPadOS, watchOS, tvOS, and visionOS.

Example

Today, I already have several Safari extensions available in the App Store, all of which are free and open-source. Some examples include Ambient Aurea, Full Screen, Zoom, Turn Off the Lights, etc.

And an example of my first pay Safari Extension Manifest V3 is the “Home Tab for Safari“. It is one price, for all your Mac and iOS devices.

After You Submit

When you submit your first Safari Extension Manifest V3, congratulations! Now, it can take between 1 and 7 working days to make your app visible. When Apple begins the app review, you will receive an email notification. The Apple team will review your App Store screenshots and text, and test it on all devices (Mac and iPhone). Once everything is in order, you will receive another email notifying you that Apple will publish your Safari extension in the App Store. Alternatively, you might receive an email indicating that you need to address a specific issue.

Addition resource

To learn more about Safari Extension Manifest V3 APIs and continue to create a creative experience for the users, see these resources:

• Chromium Extension group
• Chrome Extension Developer Documentation
• Converting a web extension for Safari
• How to distribute the app itself to the App Store
• Apple Store Review Guidelines

Conclusion

I hope you found this guide enjoyable and informative on transitioning your Chrome extension into a Safari Extension Manifest V3, especially if you are a beginner developer. Now that you are familiar with the process of getting your Apple Safari Extension Manifest V3 into the Apple ecosystem market. If you like my open work I share this with the browser extension community. And if you would like to support my work in the web community, please consider making a small donation.

Content Disclaimer: This is an individual developer article on how you upgrade your Chrome Extension to Safari Extension Manifest V3, that I want to share with the browser extension community. I am not paid by Google or Apple.