Merge pull request #824 from quoid/doc/clearer-statement-about-user.js-url

doc: clearer statement about `user.js` url support

Author: ACTCD

README.md

@@ -60,8 +60,9 @@ After installing the iOS App, you need two main steps to make the extension work
 
 There are two main ways to install a user script from the iOS version:
 
-- Visit any `.user.js` URL in Safari, then open the extension `popup` and you will see an installation prompt
-- You can also save `.user.js` files directly to the Userscripts directory you set above
+- Visit a `.user.js` URL in Safari, then open the extension `popup` and you will see an installation prompt
+  - The URL should end with `.user.js` in `/PATH` part, not the `?QUERY` or `#HASH` parts
+- You could also save files with the extension `.user.js` directly to the Userscripts directory you set above
 
 > [!TIP]
 >
@@ -177,10 +178,13 @@ Userscripts Safari currently supports the following userscript metadata:
   - when paired with `@updateURL`, this will allow the user to update a userscript from a remote source, if the version on their machine is `<` version at the update URL
   - `@version` does nothing by itself, it needs to be paired with` @updateURL` for remote updating to function properly
 - `@updateURL`
-  - the remote url to check version against
+  - the remote url to check version against, the url `/PATH` should end with `.meta.js` and contains the Metadata block
   - if the version of the file located at the update URL is `>` the version on the local machine, the file will be updated
   - `@updateURL` does nothing by itself, it needs to be paired with `@version` for remote updating to function properly
+  - Read this [link](https://stackoverflow.com/questions/38023717/) for more details
+  - _Note: The extension does not correctly implement the entire update process, tracking in issue [#248](https://github.com/quoid/userscripts/issues/248)_
 - `@downloadURL`
+  - the url `/PATH` should end with `.user.js`, that is, it cannot be in `?QUERY` or `#HASH` parts
   - optional download location for a remotely updateable file (\*i.e. a file that has both `@version` and `@updateURL`)
   - when paired with `@version` and `@updateURL`, if the local version is `<` the version of the file that `@updateURL` points to, the extension will attempt to update the file's code with the contents of the file located at the `@downloadURL`
   - `@downloadURL` does nothing by itself, it needs `@version` and `@updateURL` to present in order to function properly

src/app/_locales/en/quick-start-guide-ios.md

@@ -12,10 +12,15 @@
   - Manage extensions from the Settings App (Settings > Safari > Extensions) or Safari App (`AA` button on iPhone, `extension-icon` on iPad, the same location where you open the extension's `popup` interface).
   - For an optimal experience it's recommended that you "Always Allow" Userscripts for "All Websites", but you could also allow only the sites you want, but please don't forget your settings if your script doesn't work.
 
-### How to you install a user script
-
-- Visit any `.user.js` URL in Safari, then open the extension popup and you will see an installation prompt, or it will pop up automatically if you have enhanced prompts turned on.
-- You can also save `.user.js` files directly to the Userscripts directory. The script file must contain a valid metadata block to match the page and be displayed in the extension popup.
+### How to install and inject a user script and some things to note:
+
+- The mobile extension does not currently have a built-in script editor, but you could still write your own scripts and install them.
+- You could save files that extension with `.user.js` directly to the Userscripts directory.
+  - The script file must contain a valid metadata block to match the web pages and be displayed in the extension popup.
+- When you visit a `.user.js` URL in Safari, open the extension popup and you will see an installation prompt, or it will pop up automatically if you have enhanced prompts turned on.
+  - The URL should end with `.user.js` in `/PATH` part, not the `?QUERY` or `#HASH` parts, otherwise it will not be considered a valid user script URL by the extension.
+- When you enabled the extension and write the metadata correctly especially like `@match`, it will automatically complete the injection when you visit a matching web page.
+  - You could temporarily disable individual user scripts or all of them, just open the extension popup interface to toggle them.
 
 ### That’s it, start improving your quality of life now!
 

src/app/_locales/en/quick-start-guide-mac.md

@@ -9,9 +9,19 @@
 
 - **Enable the extension in Safari**
 
-  - Enable Userscripts in Safari extensions list.
+  - Enable Userscripts in Safari > Settings... > Extensions list.
   - For an optimal experience it's recommended that you "Always Allow" Userscripts for "All Websites", but you could also allow only the sites you want, but please don't forget your settings if your script doesn't work.
 
-That’s it, start improving your quality of life now!
+### How to install and inject a user script and some things to note:
+
+- The preferred method is of course to create your own scripts, open the extension page and click on the plus sign in the editor to create a new JS, write code and save it.
+- You could also save files that extension with `.user.js` directly to the Userscripts directory.
+  - The script file must contain a valid metadata block to match the web pages and be displayed in the extension popup.
+- When you visit a `.user.js` URL in Safari, open the extension popup and you will see an installation prompt, or it will pop up automatically if you have enhanced prompts turned on.
+  - The URL should end with `.user.js` in `/PATH` part, not the `?QUERY` or `#HASH` parts, otherwise it will not be considered a valid user script URL by the extension.
+- When you enabled the extension and write the metadata correctly especially like `@match`, it will automatically complete the injection when you visit a matching web page.
+  - You could temporarily disable individual user scripts or all of them, just open the extension popup interface to toggle them.
+
+### That’s it, start improving your quality of life now!
 
 _Hey, don't forget to read our detailed documentation to learn more._

src/app/_locales/zh/quick-start-guide-ios.md

@@ -8,13 +8,18 @@
 
 - **在 Safari 中启用扩展**
 
-  - 从设置应用程序（设置 > Safari > 扩展程序）或 Safari 应用程序（iPhone 上的“AA”按钮，iPad 上的“扩展图标”，也是您打开扩展程序的“弹出”界面的位置）管理扩展程序。
+  - 从 `设置` 应用（设置 > Safari > 扩展）或 `Safari` 应用（iPhone 上的“AA”按钮，iPad 上的“扩展图标”，也是您打开扩展的“弹出界面”的位置）管理扩展。
   - 为了获得最佳体验，建议您“始终允许” Userscripts 为“所有网站”，但您也可以仅允许您想要的网站，但当您的脚本不起作用时，请不要忘记您的设置。
 
-### 那么，如何安装用户脚本？
+### 那么，如何安装和注入用户脚本，以及一些注意事项？
 
-- 在 Safari 中访问任何 `.user.js` 网址，然后打开扩展弹出窗口，您将看到安装提示；如果您启用了增强提示，它会自动弹出。
-- 您还可以将 `.user.js` 文件直接保存到您上面设置的 Userscripts 目录中，脚本文件必须包含有效的元数据块以匹配页面并显示在扩展弹出窗口中。
+- 移动版扩展目前不包含内置的脚本编辑器，但您仍然可以编写您自己的脚本并安装它们。
+- 您可以直接保存扩展名为 `.user.js` 的文件到您上面设置的 Userscripts 目录中。
+  - 您的脚本文件必须包含有效的元数据块以匹配网站页面并正确显示在扩展的弹出界面中。
+- 当您在 Safari 中访问一个 `.user.js` 网址，然后打开扩展弹出界面，您将看到安装提示；如果您启用了增强提示，它会自动弹出。
+  - 请注意该网址的 `/路径` 部分应该以 `.user.js` 结尾，而不是 `?查询` 或 `#锚点` 部分，否则该网址将不会被视为有效的用户脚本。
+- 当您启用该扩展并正确编写元数据尤其是像 `@match` 后，当您访问匹配的网页时，它将自动完成注入。
+  - 您可以暂时禁用单个用户脚本或所有用户脚本，只需打开扩展弹出界面即可切换它们。
 
 ### 就这样，现在就开始改善您的生活质量吧！
 

src/app/_locales/zh/quick-start-guide-mac.md

@@ -8,9 +8,19 @@
 
 - **在 Safari 中启用扩展**
 
-  - 在 Safari 扩展列表中启用 Userscripts 条目。
+  - 在 Safari > 设置... > 扩展列表中启用 Userscripts 条目。
   - 为了获得最佳体验，建议您“始终允许” Userscripts 为“所有网站”，但您也可以仅允许您想要的网站，但当您的脚本不起作用时，请不要忘记您的设置。
 
-就这样，现在就开始改善您的生活质量吧！
+### 那么，如何安装和注入用户脚本，以及一些注意事项？
+
+- 首选的方法当然是撰写您自己的用户脚本，打开扩展页面点击加号创建新脚本，编辑和保存它。
+- 您还可以直接保存扩展名为 `.user.js` 的文件到您上面设置的 Userscripts 目录中。
+  - 您的脚本文件必须包含有效的元数据块以匹配网站页面并正确显示在扩展的弹出界面中。
+- 当您在 Safari 中访问一个 `.user.js` 网址，然后打开扩展弹出界面，您将看到安装提示；如果您启用了增强提示，它会自动弹出。
+  - 请注意该网址的 `/路径` 部分应该以 `.user.js` 结尾，而不是 `?查询` 或 `#锚点` 部分，否则该网址将不会被视为有效的用户脚本。
+- 当您启用该扩展并正确编写元数据尤其是像 `@match` 后，当您访问匹配的网页时，它将自动完成注入。
+  - 您可以暂时禁用单个用户脚本或所有用户脚本，只需打开扩展弹出界面即可切换它们。
+
+### 就这样，现在就开始改善您的生活质量吧！
 
 _嘿，不要忘记阅读我们的详细文档以了解更多信息。_

src/app/_locales/zh_Hant/quick-start-guide-ios.md

@@ -8,13 +8,18 @@
 
 - **在 Safari 中啟用延伸功能**
 
-  - 從設定應用程式（設定 > Safari > 延伸功能程式）或 Safari 應用程式（iPhone 上的“AA”按鈕，iPad 上的“延伸功能圖示”，也是您開啟延伸功能程式的“彈出”介面的位置）管理延伸功能程式。
+  - 從 `設定` 應用（設定 > Safari > 延伸功能）或 `Safari` 應用（iPhone 上的“AA”按鈕，iPad 上的“延伸功能圖示”，也是您開啟延伸功能的“彈出介面”的位置）管理延伸功能。
   - 為了獲得最佳體驗，建議您“始終允許” Userscripts 為“所有網站”，但您也可以僅允許您想要的網站，但當您的腳本不起作用時，請不要忘記您的設定。
 
-### 那麼，如何安裝使用者腳本？
+### 那麼，如何安裝和注入使用者腳本，以及一些注意事項？
 
-- 在 Safari 中訪問任何 `.user.js` 網址，然後開啟延伸功能彈出視窗，您將看到安裝提示；如果您啟用了增強提示，它會自動彈出。
-- 您還可以將 `.user.js` 檔案直接儲存到您上面設定的 Userscripts 目錄中，腳本檔案必須包含有效的元資料塊以匹配頁面並顯示在延伸功能彈出視窗中。
+- 移動版延伸功能目前不包含內建的腳本編輯器，但您仍然可以編寫您自己的腳本並安裝它們。
+- 您可以直接儲存副檔名為 `.user.js` 的檔案到您上面設定的 Userscripts 目錄中。
+  - 您的腳本檔案必須包含有效的元資料塊以匹配網站頁面並正確顯示在延伸功能的彈出介面中。
+- 當您在 Safari 中訪問一個 `.user.js` 網址，然後開啟延伸功能彈出介面，您將看到安裝提示；如果您啟用了增強提示，它會自動彈出。
+  - 請注意該網址的 `/路徑` 部分應該以 `.user.js` 結尾，而不是 `?查詢` 或 `#錨點` 部分，否則該網址將不會被視為有效的使用者腳本。
+- 當您啟用該延伸功能並正確編寫元資料尤其是像 `@match` 後，當您訪問匹配的網頁時，它將自動完成注入。
+  - 您可以暫時禁用單個使用者腳本或所有使用者腳本，只需開啟延伸功能彈出介面即可切換它們。
 
 ### 就這樣，現在就開始改善您的生活質量吧！
 

src/app/_locales/zh_Hant/quick-start-guide-mac.md

@@ -8,9 +8,19 @@
 
 - **在 Safari 中啟用延伸功能**
 
-  - 在 Safari 延伸功能列表中啟用 Userscripts 條目。
+  - 在 Safari > 設定... > 延伸功能列表中啟用 Userscripts 條目。
   - 為了獲得最佳體驗，建議您“始終允許” Userscripts 為“所有網站”，但您也可以僅允許您想要的網站，但當您的腳本不起作用時，請不要忘記您的設定。
 
-就這樣，現在就開始改善您的生活質量吧！
+### 那麼，如何安裝和注入使用者腳本，以及一些注意事項？
+
+- 首選的方法當然是撰寫您自己的使用者腳本，開啟延伸功能頁面點選加號建立新腳本，編輯和儲存它。
+- 您還可以直接儲存副檔名為 `.user.js` 的檔案到您上面設定的 Userscripts 目錄中。
+  - 您的腳本檔案必須包含有效的元資料塊以匹配網站頁面並正確顯示在延伸功能的彈出介面中。
+- 當您在 Safari 中訪問一個 `.user.js` 網址，然後開啟延伸功能彈出介面，您將看到安裝提示；如果您啟用了增強提示，它會自動彈出。
+  - 請注意該網址的 `/路徑` 部分應該以 `.user.js` 結尾，而不是 `?查詢` 或 `#錨點` 部分，否則該網址將不會被視為有效的使用者腳本。
+- 當您啟用該延伸功能並正確編寫元資料尤其是像 `@match` 後，當您訪問匹配的網頁時，它將自動完成注入。
+  - 您可以暫時禁用單個使用者腳本或所有使用者腳本，只需開啟延伸功能彈出介面即可切換它們。
+
+### 就這樣，現在就開始改善您的生活質量吧！
 
 _嘿，不要忘記閱讀我們的詳細文件以瞭解更多資訊。_

xcode/Ext-Safari/Functions.swift

@@ -59,10 +59,12 @@ func validateUrl(_ urlString: String) -> Bool {
 		logger?.error("\(#function, privacy: .public) - Invalid URL: \(urlString, privacy: .public)")
 		return false
 	}
-	if
-		(ptcl != "https:" && ptcl != "http:")
-		|| (!path.hasSuffix(".css") && !path.hasSuffix(".js"))
-	{
+	if ptcl != "https:" && ptcl != "http:" {
+		logger?.error("\(#function, privacy: .public) - Invalid URL protocol: \(urlString, privacy: .public)")
+		return false
+	}
+	if !path.hasSuffix(".css") && !path.hasSuffix(".js") {
+		logger?.error("\(#function, privacy: .public) - Invalid URL suffix: \(urlString, privacy: .public)")
 		return false
 	}
 	return true
@@ -829,7 +831,7 @@ func checkForRemoteUpdates(_ optionalFilesArray: [[String: Any]] = []) -> [[Stri
 			let currentVersion = metadata["version"]![0]
 			let updateUrl = metadata["updateURL"]![0]
 			// before fetching remote contents, ensure it points to a file of the same type
-			if !updateUrl.hasSuffix(type) {continue}
+			if !validateUrl(updateUrl) {continue}
 			guard
 				let remoteFileContents = getRemoteFileContents(updateUrl),
 				let remoteFileContentsParsed = parse(remoteFileContents),
@@ -1812,7 +1814,7 @@ func getFileRemoteUpdate(_ content: String) -> [String: String] {
 		return ["error": "Update failed, couldn't parse remote file contents"]
 	}
 	// check if update is needed
-	if version >= remoteVersion {
+	if !isVersionNewer(version, remoteVersion) {
 		return ["info": "No updates found"]
 	}
 	// at this point it is known an update is available, get new code from downloadURL