1. English README.md

Google Sheet Rank Tracker - Setup Guide

This guide will walk you through setting up and using the Google Apps Script to automatically track your website's keyword rankings in Google search, directly within your spreadsheet.

What This Script Does

This script adds a custom menu to your Google Sheet that, when run, will:

• Read keywords from Column A.
• Check their Google ranking using the Serper.dev API.
• Support both English and Persian, including dates, comments, and search language, based on a single setting.
• Perform localized searches (US for English, Iran for Persian) for more accurate results.
• Insert the ranks into a new, automatically dated column.
• Compare the ranking URL with a target URL you provide in Column C.
• Add a comment to the rank cell if the found URL does not match your target URL.
• Prepare for the next run by automatically placing an <InsertFlag> in the next available column.

Prerequisites

1. A Google Account with access to Google Sheets.
2. A Serper.dev API Key:
   • Go to serper.dev.
   • Sign up for a free account.
   • Go to your dashboard to find your API Key. Copy it.

Step 1: Prepare Your Google Sheet

Your Google Sheet must be formatted correctly for the script to work.

1. Open your spreadsheet in Google Sheets.
2. Cell A1: Must contain your main domain (e.g., example.com).
3. Row 2 (Headers): This is your header row. At least one empty column's header must be exactly <InsertFlag>. This tells the script where to put the new ranks.
4. Column A: Starting from cell A3, list all the keywords you want to track.
5. Column C: (Optional) Starting from cell C3, you can place the specific URL you expect to rank for the corresponding keyword in that row.

Example Sheet Structure:

	A	B	C	D	E
1	example.com,,,,
2	Keyword	Type	Target URL	2024-05-21	<InsertFlag>
3	Keyword 1	PLP	https://example.com/page-1	4
4	Keyword 2	PLP	https://example.com/page-2	2
5	Keyword 3	Blog	https://example.com/blog/post	1

Step 2: Install the Script

1. In your Google Sheet, click on the menu Extensions > Apps Script. A new browser tab will open with the script editor.
2. Delete any default code in the editor (e.g., function myFunction() {}).
3. Copy the entire script code provided to you and paste it into the empty script editor.

Step 3: Configure the Script

This is the most important step. At the top of the script, you will find the CONFIGURATION section.

// --- CONFIGURATION ---
// Your Serper.dev API Key.
const API_KEY = "<your_api_key_here>";

// Set to true for Persian (Jalali dates, Farsi comments, Farsi search).
// Set to false for English (YYYY-MM-DD dates, English comments, English search).
const ENABLE_FARSI = false; 

// The maximum number of results to fetch from Serper API.
const MAX_RANK = 30;
// --- END OF CONFIGURATION ---

1. API_KEY: Replace <your_api_key_here> with the actual API key you copied from your Serper.dev dashboard. Keep the quotation marks.

2. ENABLE_FARSI: This flag controls the language and formatting.

   • Set it to true if you are working with Persian keywords and want Persian (Jalali) dates and Farsi comments.
   • Set it to false if you are working with English keywords and want standard YYYY-MM-DD dates and English comments.

3. MAX_RANK: The maximum number of Google search results to check for your domain (e.g., 30 means the script checks the top 30 results).

4. Click the Save project icon (it looks like a floppy disk).

Step 4: Run the Script for the First Time (Authorization)

1. Go back to your Google Sheet tab and refresh the page.
2. A new menu will appear named 🚀 Rank Checker.
3. Click the menu and select Run Keyword Rank Check.
4. A dialog box will appear asking for Authorization Required. Click Continue.
5. Choose your Google account.
6. You will likely see a warning screen saying "Google hasn’t verified this app". This is normal and safe because it's your own script.
   • Click Advanced.
   • Click Go to [Your Project Name] (unsafe).
7. Review the permissions the script needs and click Allow.

How to Use the Rank Tracker

Once set up, simply click the 🚀 Rank Checker menu and select the run option. A pop-up will confirm the script is starting. Click OK, and the script will process all your keywords.

Understanding the Output

• New Column: The <InsertFlag> header will be replaced with the current date (e.g., 2024-05-21).
• Ranks: A number (e.g., 3) indicates your domain's rank.
• Not Found: Your domain was not found in the top results (as defined by MAX_RANK).
• URL Mismatch Comments: If a rank cell has a black triangle in the corner, hover over it to see a comment comparing the expected URL from Column C and the actual URL found in the search results.

🤝 Contributing

Pull requests are welcome! Whether it's a bug fix, feature suggestion, or just a typo, feel free to open a PR.
If you're unsure about something, open an issue and let's discuss it. 🚀

📄 License

This project is licensed under the Apache License 2.0.

---

---

2. Persian (Farsi) README.md

راهنمای نصب و راه‌اندازی رتبه سنج گوگل شیت

این راهنما شما را قدم به قدم برای نصب و استفاده از اسکریپت ردیابی رتبه کلمات کلیدی در گوگل شیت همراهی می‌کند.

این اسکریپت چه کاری انجام می‌دهد؟

این اسکریپت یک منوی سفارشی به گوگل شیت شما اضافه می‌کند که با اجرای آن، کارهای زیر انجام می‌شود:

• خواندن کلمات کلیدی از ستون A.
• بررسی رتبه آن‌ها در گوگل با استفاده از سرویس Serper.dev.
• پشتیبانی کامل از زبان فارسی و انگلیسی، شامل تاریخ شمسی، کامنت‌های فارسی و زبان جستجو که با یک تنظیم ساده فعال می‌شود.
• انجام جستجوی محلی‌سازی شده (ایران برای فارسی، آمریکا برای انگلیسی) برای دریافت نتایج دقیق‌تر.
• درج رتبه‌ها در یک ستون جدید با تاریخ روز.
• مقایسه لینک رتبه با لینک دلخواه شما که در ستون C وارد کرده‌اید.
• افزودن کامنت به سلول رتبه در صورتی که لینک پیدا شده با لینک مدنظر شما مغایرت داشته باشد.
• آماده‌سازی خودکار برای اجرای بعدی با قرار دادن <InsertFlag> در ستون خالی بعدی.

پیش‌نیازها

۱. اکانت گوگل با دسترسی به گوگل شیت. ۲. کلید API از سایت Serper.dev: - به سایت serper.dev بروید. - یک حساب کاربری رایگان بسازید. - از داشبورد حساب کاربری خود، API Key را کپی کنید.

مرحله ۱: آماده‌سازی گوگل شیت

گوگل شیت شما باید فرمت مشخصی داشته باشد تا اسکریپت به درستی کار کند.

۱. فایل خود را در گوگل شیت باز کنید. ۲. سلول A1: باید شامل دامنه اصلی سایت شما باشد (مثلاً example.com). ۳. ردیف ۲ (سرتیترها): این ردیف سرتیتر ستون‌هاست. سرتیتر یکی از ستون‌های خالی باید دقیقاً <InsertFlag> باشد. اسکریپت رتبه‌های جدید را در این ستون وارد می‌کند. ۴. ستون A: از ردیف ۳ به بعد، لیست کلمات کلیدی مورد نظر خود را وارد کنید. ۵. ستون C: (اختیاری) از ردیف ۳ به بعد، می‌توانید لینکی که انتظار دارید برای کلمه کلیدی همان ردیف رتبه بگیرد را وارد کنید.

نمونه ساختار فایل:

	A	B	C	D	E
1	example.com,,,,
2	کلمه کلیدی	نوع	لینک هدف	رتبه (۱۴۰۳/۳/۱)	<InsertFlag>
3	کلمه کلیدی ۱	محصول	https://example.com/page-1	4
4	کلمه کلیدی ۲	محصول	https://example.com/page-2	2
5	کلمه کلیدی ۳	بلاگ	https://example.com/blog/post	1

مرحله ۲: نصب اسکریپت

۱. در منوی گوگل شیت، روی Extensions > Apps Script کلیک کنید تا ویرایشگر اسکریپت در تب جدیدی باز شود. ۲. تمام کدهای پیش‌فرض موجود در ویرایشگر را پاک کنید. ۳. کل کد اسکریپت را که در اختیار دارید کپی کرده و در ویرایشگر خالی پیست (Paste) کنید.

مرحله ۳: پیکربندی اسکریپت

این مهم‌ترین مرحله است. در بالای کد اسکریپت، بخش CONFIGURATION را پیدا کنید.

// --- CONFIGURATION ---
// Your Serper.dev API Key.
const API_KEY = "<your_api_key_here>";

// Set to true for Persian (Jalali dates, Farsi comments, Farsi search).
// Set to false for English (YYYY-MM-DD dates, English comments, English search).
const ENABLE_FARSI = true; 

// The maximum number of results to fetch from Serper API.
const MAX_RANK = 30;
// --- END OF CONFIGURATION ---

۱. فلگ API_KEY: به جای <your_api_key_here>، کلید API واقعی خود را که از سایت Serper.dev گرفته‌اید، قرار دهید. حتماً آن را داخل دابل کوتیشن "" نگه دارید.

۲. فلگ ENABLE_FARSI: این فلگ، زبان و فرمت اسکریپت را کنترل می‌کند. - اگر با کلمات کلیدی فارسی کار می‌کنید و می‌خواهید تاریخ‌ها شمسی و کامنت‌ها فارسی باشند، آن را روی true تنظیم کنید. - اگر با کلمات انگلیسی کار می‌کنید و تاریخ میلادی و کامنت انگلیسی می‌خواهید، آن را روی false تنظیم کنید.

۳. فلگ MAX_RANK: حداکثر تعداد نتایج جستجوی گوگل که اسکریپت برای پیدا کردن دامنه شما بررسی می‌کند (مثلاً عدد ۳۰ یعنی ۳۰ نتیجه اول گوگل چک می‌شود).

۴. روی آیکون Save project (شبیه به فلاپی دیسک) کلیک کنید تا تغییرات ذخیره شود.

مرحله ۴: اجرای اولیه و دادن دسترسی (Authorization)

۱. به تب گوگل شیت خود برگردید و صفحه را رفرش (Refresh) کنید. ۲. یک منوی جدید به نام 🚀 رتبه سنج به منوهای اصلی اضافه خواهد شد. ۳. روی این منو کلیک کرده و گزینه شروع بررسی رتبه کلمات کلیدی را انتخاب کنید. ۴. یک پنجره برای Authorization Required باز می‌شود. روی Continue کلیک کنید. ۵. اکانت گوگل خود را انتخاب کنید. ۶. به احتمال زیاد یک صفحه هشدار با عنوان "Google hasn’t verified this app" خواهید دید. این کاملاً طبیعی و امن است، زیرا این اسکریپت شخصی خودتان است. - روی Advanced کلیک کنید. - سپس روی Go to [Your Project Name] (unsafe) کلیک کنید. ۷. دسترسی‌های مورد نیاز اسکریپت را بازبینی و روی Allow کلیک کنید.

نحوه استفاده

پس از نصب، کافیست از منوی 🚀 رتبه سنج، گزینه اجرای اسکریپت را انتخاب کنید. یک پاپ‌آپ برای تایید شروع عملیات نمایش داده می‌شود. با کلیک روی OK، اسکریپت کار خود را آغاز می‌کند.

درک خروجی اسکریپت

• ستون جدید: سرتیتر <InsertFlag> با تاریخ روز و کلمه "رتبه" جایگزین می‌شود (مثلاً رتبه (۱۴۰۳/۳/۱)).
• رتبه‌ها: یک عدد (مانند 3) نشان‌دهنده رتبه دامنه شماست.
• Not Found: یعنی دامنه شما در نتایج برتر گوگل (به تعدادی که در MAX_RANK مشخص شده) پیدا نشده است.
• کامنت مغایرت لینک: اگر در گوشه یک سلول رتبه، یک مثلث سیاه کوچک وجود داشت، به این معناست که لینک رتبه گرفته با لینک هدف شما در ستون C متفاوت است. ماوس را روی آن سلول نگه دارید تا کامنت حاوی لینک مورد انتظار و لینک پیدا شده را ببینید.

🤝 مشارکت

درخواست‌های تغییر (Pull Request) با آغوش باز پذیرفته می‌شوند!
اگر در مورد چیزی مطمئن نیستید، یک Issue ایجاد کنید تا با هم صحبت کنیم. 🚀

📄 مجوز

این پروژه تحت مجوز Apache License 2.0 منتشر شده است.