getting-started

Getting Started with Ranksy

Getting Started with Ranksy Ranksy onboarding Welcome to Ranksy! This guide will help you set up your account and start tracking your Shopify app's performance in just a few minutes. What is Ranksy? Ranksy is your all-in-one analytics platform for Shopify app developers. Think of it as your app's command center where you can: - Track Performance: See how your app ranks in categories and for keywords - Understand Revenue: Know exactly which channels drive paying customers - Research Competition: Monitor what successful apps are doing - Manage Customers: View and analyze all your app users in one place - Make Better Decisions: Use real data instead of guessing Whether you're a solo developer with one app or an agency managing multiple clients, Ranksy gives you the insights you need to grow. Step 1: Create Your Account Sign Up with Google (Recommended - 30 seconds) The fastest way to get started: 1. Go to ranksyapp.com/register 2. Click the "Sign up with Google" button 3. Choose your Google account 4. Click "Allow" to grant permissions 5. You're in! 🎉 Why Google? It's faster, more secure, and you don't need to remember another password. Sign Up with Email (2 minutes) Prefer email and password? 1. Go to ranksyapp.com/register 2. Enter your email address 3. Create a strong password (at least 8 characters) 4. Click "Create Account" 5. Check your email inbox 6. Click the verification link in the email 7. Your account is now active! 💡 Pro Tip: Check your spam folder if you don't see the verification email within 5 minutes. Step 2: Add Your App (1 minute) Now let's add your Shopify app to Ranksy: Finding Your App 1. After logging in, use the search bar at the top 2. Type your app's name 3. Click on your app from the search results Can't find your app? - Make sure it's published on the Shopify App Store - Try searching for part of the name - Check the spelling Adding to My Apps 1. On your app's profile page, click "Add to My Apps" 2. The button instantly changes to "Remove from My Apps" That's it! Your app is now in your portfolio and ready for analytics. Step 3: Connect Your Data Sources This is the most important step! Connecting your data sources unlocks all of Ranksy's powerful analytics. Why Connect Data? Without data connections, you can only see basic public information. With connections, you get: - Revenue and MRR tracking - Customer lifecycle analysis - Traffic and conversion data - Complete attribution tracking Think of it like connecting your bank account to accounting software - you need the connection to see your real numbers. Connection 1: Shopify Partner API (Revenue Data) This connects your Shopify Partner account so Ranksy can track your app's revenue and customers. What You'll Need: - Your Shopify Partner Organization ID - An API access key - Your app's ID Where to Find These: 1. Log into your Shopify Partner Dashboard 2. Go to Settings → Partner Account 3. Note your Organization ID (looks like: 123456) 4. Go to Apps → Your app → Note the App ID from the URL 5. Go back to Settings → API access → Create a new API key In Ranksy: 1. Click on your app in My Apps 2. Go to Settings 3. Find the "Shopify Partner API" section 4. Enter your Organization ID, API Key, and App ID 5. Click "Test Connection" to make sure it works 6. Click "Save" 7. Click "Run Historical Sync" to import past data ⏱️ How long? Initial sync takes 30 minutes to 2 hours depending on your data volume. Connection 2: Google BigQuery (Traffic Data) This connects your Google Analytics data so Ranksy can show you traffic, sessions, and user behavior. Prerequisites: - Google Analytics 4 (GA4) set up for your app - GA4 connected to BigQuery (free tier works!) - BigQuery data viewer permissions In Ranksy: 1. In your app Settings, find "Google BigQuery" 2. Click "Connect Google Account" 3. Choose your Google account 4. Click "Allow" to grant permissions 5. Select your Google Cloud Project (where GA4 exports data) 6. Select your GA4 dataset (usually named analytics_123456789) 7. Click "Test Import" to verify 8. Click "Save" and "Start Import" ⏱️ How long? First import takes 1-4 hours for a year of historical data. ⚠️ Important: Set up both integrations right away! Every day you wait is a day of data you'll miss forever. Step 4: Explore Your Dashboard (2 minutes) Ranksy dashboard overview While your data is syncing, let's look around: Your Analytics Dashboard Click on your app in "My Apps" to see: Key Metrics Cards showing: - Pageviews (people viewing your app) - Add App Clicks (people clicking to install) - Installs (actual installations) - Revenue trends (when Partner API is connected) Daily Events Chart showing: - Traffic patterns over time - Spike when you launch features - Trends you should pay attention to Conversion Funnel showing: - How many people see your app - How many click to install - How many actually install - Where you're losing potential customers Top Traffic Sources: - Where your visitors come from - Which channels convert best - Where to focus marketing efforts Other Important Sections Category Analytics: See your ranking in each Shopify category Search Analytics: Track which keywords drive traffic Customer Management: View all your app users Partner Metrics: Deep dive into revenue and MRR What to Do While Data Syncs While your integrations are pulling historical data, here's what you can do: 1. Research Your Competition (10 minutes) 1. Go to Apps in the main menu 2. Filter by your app's category 3. Sort by rating or reviews 4. Click on top-performing apps 5. Click "Follow" on 3-5 key competitors Now you'll get updates when they: - Release new features - Move up or down in rankings - Get new reviews 2. Explore the App Store (10 minutes) Browse the Categories section to: - See how many apps are in each category - Check average ratings - Identify underserved niches - Find new opportunities 3. Research Keywords (10 minutes) Go to Keywords to see: - What people are searching for - Which keywords have less competition - Which terms drive the most traffic - Where your app could rank First Week Best Practices Monday Morning Routine (5 minutes) 1. Open Ranksy 2. Check your Analytics Dashboard 3. Look for unusual spikes or drops 4. Review yesterday's key metrics 5. Check your ranking positions Mid-Week Check (10 minutes) 1. Review traffic sources 2. Check conversion rates 3. Monitor customer growth 4. See what competitors are doing Friday Review (15 minutes) 1. Look at week-over-week changes 2. Analyze what worked (and what didn't) 3. Plan next week's optimizations 4. Set goals for the following week Common Questions Q: How soon will I see data? A: Basic app store data shows immediately. Partner API takes 30min-2hr. BigQuery takes 1-4hr for full historical import. Q: Do I really need both integrations? A: For complete analytics, yes. Partner API = revenue data. BigQuery = traffic data. Together = full picture of your business. Q: Can I add multiple apps? A: Absolutely! Add as many apps as you manage. Perfect for agencies and multi-app developers. Q: Is my data secure? A: Yes. All data is encrypted in transit and at rest. We're GDPR compliant and never share your data. Q: What if I need help? A: Use the chat widget (bottom right), email [email protected], or check docs.ranksyapp.com. Q: Can I try before connecting my data? A: Yes! Add your app and explore public data first. You can connect integrations whenever you're ready. Quick Troubleshooting "I can't find my app" - Make sure it's published on Shopify App Store - Try searching by partial name - Check if it's in the correct category "Partner API connection failed" - Double-check your Organization ID - Make sure API key is copied correctly (no extra spaces) - Verify the API key has proper permissions - Try generating a new API key "BigQuery import isn't working" - Confirm GA4 is exporting to BigQuery - Check you have "BigQuery Data Viewer" permissions - Verify you selected the correct project and dataset - Make sure billing is enabled on your Google Cloud project "No data showing yet" - Check integration status in Settings - Look for error messages - Wait for initial sync to complete - Try clicking "Sync Now" to trigger manually You're All Set! 🚀 You now have: - ✅ Your account created - ✅ Your app added - ✅ Data sources connected (or in progress) - ✅ Understanding of the dashboard Next Steps: 1. Bookmark your Analytics Dashboard 2. Set up a daily 5-minute review routine 3. Follow your top 3-5 competitors 4. Explore all the features 5. Make your first data-driven decision! Welcome to smarter Shopify app development. Happy growing! 🌱 Need More Help? - Browse Guides: Check out our detailed guides on each feature - Video Tutorials: Watch step-by-step videos (coming soon) - Contact Support: [email protected] - Schedule Demo: Book a personal walkthrough Remember: The best time to start tracking your data was yesterday. The second best time is right now.

Setting Up Integrations

How to Set Up Your Data Integrations Integration settings overview Setting up your data integrations is the most important thing you'll do in Ranksy. This guide will walk you through connecting both the Shopify Partner API and Google BigQuery step-by-step. Why Integrations Matter Think of Ranksy without integrations like a car without an engine - it looks nice, but it won't take you anywhere. Here's what you're missing without integrations: Without Integrations: - ❌ No revenue data - ❌ No customer information - ❌ No traffic sources - ❌ No conversion tracking - ❌ Can only see public app store data With Integrations: - ✅ Complete revenue and MRR tracking - ✅ Full customer lifecycle analysis - ✅ Traffic source attribution - ✅ Conversion funnel visualization - ✅ Know exactly what drives your business Bottom line: Skip this and you're flying blind. Do this and you have superpowers. Integration 1: Shopify Partner API This connects your Shopify Partner account to Ranksy so we can track your app's revenue, customers, and subscriptions. What Data Do You Get? Once connected, Ranksy will show you: - Revenue: Daily, weekly, monthly earnings - MRR (Monthly Recurring Revenue): Your predictable income - Customer Count: Total paying customers - New Installs: People who just added your app - Churn: Customers who cancelled - Subscription Changes: Upgrades and downgrades - Customer List: Every merchant using your app Before You Start Make sure you have: - Access to your Shopify Partner Dashboard - Admin permissions for your app - 10 minutes of uninterrupted time Step-by-Step Setup Part 1: Get Your Credentials from Shopify 1. Get Your Organization ID 1. Log into partners.shopify.com 2. Click on Settings (gear icon in top right) 3. Go to Partner account settings 4. You'll see Organization ID - it's a number like 123456 5. Copy this number and paste it somewhere safe (Notes app, etc.) 2. Get Your App ID 1. In Partner Dashboard, go to Apps 2. Click on your app 3. Look at the URL in your browser 4. You'll see something like: partners.shopify.com/123456/apps/789012 5. The last number (789012) is your App ID 6. Copy this number 3. Generate an API Access Key 1. In Partner Dashboard, go to Settings again 2. Click API access 3. Click Generate API key or Create API key 4. Give it a name like "Ranksy Analytics" 5. Copy the API key immediately (you can only see it once!) 6. Store it somewhere safe ⚠️ Important: Treat this API key like a password! Don't share it or commit it to GitHub. Part 2: Enter Credentials in Ranksy 1. Go to Your App Settings - In Ranksy, click My Apps - Click on your app - Click Settings in the navigation 2. Find Shopify Partner API Section - Scroll to find "Shopify Partner API Integration" - Click Configure or Connect 3. Enter Your Credentials - Organization ID: Paste the number from Step 1.1 - API Access Key: Paste the key from Step 1.3 - App ID: Paste the number from Step 1.2 4. Test the Connection - Click Test Connection - Wait 5-10 seconds - You should see: ✅ "Connection successful!" - If you see an error, double-check your credentials 5. Save and Sync - Click Save Configuration - Click Run Historical Sync - This imports all your past revenue and customer data Part 3: Wait for Data Timeline: - Initial sync: 30 minutes to 2 hours - Depends on: How long your app has been live and how many customers you have What's Happening: Ranksy is downloading: - Every transaction since your app launched - Every customer install and uninstall - All subscription changes - Complete revenue history While You Wait: - The Settings page shows sync progress - You can close the page - sync continues in background - You'll see partial data appear as it imports Troubleshooting Partner API Error: "Invalid Organization ID" - Double-check you copied the whole number - Make sure there are no spaces before or after - Try copying it again from Shopify Error: "Invalid API Key" - The key is case-sensitive - copy carefully - No spaces at the beginning or end - If you lost the key, generate a new one in Shopify Error: "App Not Found" - Verify the App ID is correct - Make sure it's the app ID, not organization ID - Check the URL format in Shopify Partner Dashboard Sync Takes Forever - Large app with years of data? Can take 2-4 hours - Check status in Settings page - Contact support if stuck for more than 6 hours Data Doesn't Match Partner Dashboard - Click "Full Sync" to refresh everything - Check date ranges match - Some metrics calculated differently (we'll explain why) Integration 2: Google BigQuery This connects your Google Analytics 4 (GA4) data to Ranksy so we can show you traffic, sessions, conversions, and user behavior. What Data Do You Get? Once connected, Ranksy shows: - Traffic Sources: Where visitors come from (Google, Facebook, Direct, etc.) - Pageviews: How many people view your app listing - Sessions: Complete user journeys - Geographic Data: Where your users are located - Device Data: Mobile vs desktop traffic - Click Events: What users click on - Conversion Tracking: From view to install - Attribution: Which channels drive paying customers Prerequisites (Important!) You MUST have these set up BEFORE connecting BigQuery: ✅ Google Analytics 4 (GA4) installed on your app ✅ GA4 linked to BigQuery (free tier works!) ✅ BigQuery Data Export enabled ✅ At least 24 hours of data exported Don't have these? No problem - see the "Setting Up BigQuery Export" section below first. Step-by-Step Setup Part 1: Verify BigQuery Export is Working 1. Go to console.cloud.google.com 2. Select your Google Cloud Project 3. Go to BigQuery (use search bar if needed) 4. In the left sidebar, expand your project 5. Look for a dataset named analytics_XXXXXXXXX (your GA4 property ID) 6. Expand that dataset 7. You should see tables like: - events_20250112 (today's date) - events_20250111 (yesterday's date) - events_intraday_20250112 (realtime data) If you see these tables, you're ready! If not, see "Setting Up BigQuery Export" below. Part 2: Connect in Ranksy 1. Go to Your App Settings - In Ranksy, go to My Apps → Your app → Settings - Find "Google BigQuery Integration" 2. Connect Your Google Account - Click Connect Google Account - A Google sign-in window opens - Choose your Google account (use the same one that owns the BigQuery project) - Click Allow to grant permissions What permissions are we asking for? - Read your BigQuery datasets (to import GA4 data) - View your Google Cloud projects (to find your datasets) - That's it! We can't modify or delete anything. 3. Select Your Project - After connecting, you'll see a dropdown - Select the Google Cloud Project where GA4 exports data - This is usually named after your company or app 4. Select Your Dataset - Another dropdown appears - Choose the analytics_XXXXXXXXX dataset - This is where GA4 exports your data 5. Configure Import Settings - Import Historical Data? Yes (recommended) - Date Range: Last 365 days (or choose custom) - Include Intraday Tables? Yes (for near-realtime data) 6. Test the Import - Click Test Import - Ranksy will try to read a sample of your data - You should see: ✅ "Found X events from [date]" - If error, see troubleshooting below 7. Save and Import - Click Save Configuration - Click Start Historical Import - Import begins immediately Part 3: Wait for Import Timeline: - 7 days of data: 15-30 minutes - 30 days: 1 hour - 1 year: 2-4 hours What's Happening: Ranksy is: - Reading all your GA4 event tables - Processing pageviews, clicks, sessions - Calculating traffic sources - Building attribution models - Creating your customer journeys Progress Tracking: - Settings page shows import progress - "Last Import" timestamp updates - Partial data appears as it imports Troubleshooting BigQuery Error: "No datasets found" - Make sure GA4 is exporting to BigQuery - Wait 24-48 hours after enabling export - Check you selected the correct Google Cloud project - Verify billing is enabled on your project Error: "Permission denied" - You need "BigQuery Data Viewer" role minimum - Go to Google Cloud Console → IAM & Admin - Check your account has proper permissions - Try disconnecting and reconnecting your Google account Error: "Dataset not found" - Confirm GA4 export is enabled - Check dataset name matches analytics_XXXXXXXXX format - Verify project is correct - Look in BigQuery console to see if tables exist Import Fails Repeatedly - Check BigQuery quota limits (free tier is generous but has limits) - Verify internet connection is stable - Try smaller date range first (last 7 days) - Contact support with error message No Data Shows in Ranksy - Verify GA4 tracking is working (check Google Analytics) - Confirm events are being collected - Check date range selection in Ranksy - Wait for daily export to complete (happens overnight) Setting Up BigQuery Export (If You Haven't Already) Don't have BigQuery export set up yet? Here's how: Part 1: Link GA4 to BigQuery 1. Go to analytics.google.com 2. Click Admin (gear icon, bottom left) 3. In the Property column, click BigQuery Links 4. Click Link 5. Choose your Google Cloud Project (or create a new one) 6. Click Next 7. Select your data streams 8. Configure settings: - Daily: Exports complete daily data (recommended: ON) - Streaming: Real-time export (recommended: ON if you have volume) - Include today's data: Yes 9. Click Submit 10. Wait 24-48 hours for first export Part 2: Enable Billing (Required but Can Be Free!) Google requires billing enabled, BUT: - First 1 TB of queries per month is FREE - Free 10 GB storage - Most apps stay within free tier To enable: 1. Go to console.cloud.google.com 2. Select your project 3. Go to Billing 4. Link a billing account (or create one) 5. Set up budget alerts at $0.01 to monitor usage 💡 Pro Tip: Set a budget alert so you know if you're approaching paid usage (you probably won't). Integration Maintenance Keep Your Integrations Healthy Weekly Check (30 seconds): - Look at "Last Sync" timestamp in Settings - Should be within last 24 hours - Look for any error messages Monthly Tasks (5 minutes): - Review BigQuery usage costs (probably $0!) - Check both integrations still connected - Verify data looks accurate When to Re-sync: - If data looks off - After changing credentials - If sync fails multiple times - When onboarding new team members Automatic Syncs Once connected, Ranksy automatically: - Partner API: Syncs once per day (overnight) - BigQuery: Imports new daily tables each morning - Intraday: Checks for near-realtime data every 4 hours You don't need to do anything - it just works! Security & Privacy How We Handle Your Data Credentials Storage: - Encrypted at rest using industry-standard AES-256 - Encrypted in transit with TLS/SSL - Never stored in plain text - Access logged and monitored Data Access: - Read-only access to your data - We NEVER modify your Shopify or Google data - Your data stays yours - Isolated per account - no cross-contamination Compliance: - GDPR compliant - SOC 2 practices - Regular security audits - Data processing agreements available Your Rights You can always: - Export your data (CSV/Excel anytime) - Disconnect integrations (Settings → Disconnect) - Delete your data (90-day retention, then permanent deletion) - Request data processing agreement FAQ Q: Do I really need BOTH integrations? A: For complete analytics, yes. Partner API gives you money data. BigQuery gives you traffic data. Together you see the full picture. Q: Can I connect later? A: Yes, but you'll lose historical data for the days you're not connected. Best to connect immediately. Q: What if my API key leaks? A: Generate a new one in Shopify Partner Dashboard immediately. Update it in Ranksy Settings. Old key stops working. Q: Does this affect my Shopify billing? A: No. Partner API is free to use (within reasonable limits). Q: Will BigQuery cost me money? A: Probably not. Most apps stay within Google's free tier (1 TB queries/month free). Typical cost if you exceed: $5-20/month. Q: Can I pause syncing? A: Yes. Toggle "Automatic Sync" off in Settings. Manual sync still available. Can re-enable anytime. Q: What if I have multiple apps? A: Connect each app separately. Use same or different credentials (your choice). Q: How do I disconnect? A: Settings → Find integration → Click "Disconnect" → Confirm. Historical data retained for 90 days. Getting Help Still Stuck? Check These First: 1. Error messages in Settings (click for details) 2. "Last Sync" timestamps 3. Integration status indicators (green = good, red = issue) Contact Support: - Email: [email protected] - Chat: Click widget in bottom right - Include: Screenshots of any errors + your app name Urgent Issues: - Subject line: "URGENT: Integration Issue" - We respond within 2 hours during business hours Success Checklist Before you consider integrations "done", verify: - ✅ Partner API showing green "Connected" status - ✅ BigQuery showing green "Connected" status - ✅ Revenue numbers appear in Analytics Dashboard - ✅ Traffic data showing in Analytics Dashboard - ✅ "Last Sync" timestamps are recent (within 24 hours) - ✅ No error messages in Settings - ✅ Customer count matches (roughly) Partner Dashboard Once all checked off, you're good to go! 🎉 What's Next? Now that your data is flowing: 1. Understanding Your Analytics Dashboard - Learn what all those numbers mean 2. Tracking Your Rankings - Monitor category and keyword positions 3. Managing Customers - Use the built-in CRM Remember: The hardest part is done. Now you can focus on growing your app with real data!

Connect Partner API

How to Connect Shopify Partner API Connect your Shopify Partner account to Ranksy to track revenue, customers, subscriptions, and business metrics for your app. What You'll Get Once connected, Ranksy automatically imports: - Revenue Data: Daily, weekly, monthly earnings - MRR (Monthly Recurring Revenue): Predictable income tracking - Customer Count: Total paying customers - New Installs: Recent app installations - Churn: Customers who cancelled - Subscription Changes: Upgrades and downgrades - Customer Details: Complete merchant information Before You Start Make sure you have: ✅ Access to your Shopify Partner Dashboard ✅ Admin permissions for your app ✅ 5-10 minutes to gather credentials Step 1: Get Your Credentials from Shopify You need three pieces of information from your Shopify Partner Dashboard. 1. Organization ID 1. Log into partners.shopify.com 2. Click Settings (gear icon in top right) 3. Go to Partner account settings 4. Find your Organization ID (looks like: 123456) 5. Copy this number 2. App ID 1. In Partner Dashboard, go to Apps 2. Click on your app 3. Look at the URL in your browser address bar 4. The URL looks like: partners.shopify.com/123456/apps/789012 5. The last number (789012) is your App ID 6. Copy this number 3. API Access Token Shopify generates this token from a Partner API client. (This replaces the older single-use "API access" keys.) 1. In your Partner Dashboard, click Settings (gear icon in the top right) 2. Scroll down to the Partner API clients section 3. Click Manage Partner API clients 4. Click Create Partner API client 5. Give it a name like Ranksy 6. Under Permissions → Permission sets, tick: - ✅ View financials (required — for earnings and revenue) - ✅ Manage apps (required — for app events and installs) - Leave Manage themes unchecked 7. Save to create the client 8. Open the client and find the Credentials section 9. Next to Access token, click Show (or the copy icon) and copy the token 💡 Good to know: Unlike the old API keys, you can view and copy this access token again anytime from the same screen — it isn't shown only once. To rotate credentials later without downtime, use Generate secondary token instead of deleting the client. ⚠️ Important: Treat this access token like a password. Don't share it or commit it to code repositories. Step 2: Enter Credentials in Ranksy Now let's connect your Partner account to Ranksy. Navigate to Settings 1. In Ranksy, go to My Apps 2. Click on your app 3. Click Settings in the app navigation Enter Your Credentials In the "Shopify Partner API" section: 1. Enter your Organization ID 2. In the API Key field, paste the Partner API client Access token (it will be masked as you type) 3. Enter your App ID 4. Click "Save Configuration" That's it! Ranksy will immediately start syncing your data. What Happens After Save? When you click "Save Configuration": 1. Ranksy validates your credentials 2. A sync is automatically triggered 3. Historical data starts importing 4. You'll see a success message Note: There's no separate "Start Sync" button - saving your credentials automatically starts the import process. Step 3: Monitor the Sync Check Sync Status The Settings page shows: - Last sync time - Sync status (Connected, Syncing, Error) - Number of records imported How Long Does It Take? First sync duration depends on your data: - New app (< 6 months): 15-30 minutes - Established app (6-24 months): 30-60 minutes - Mature app (2+ years): 1-2 hours You can close the page - sync continues in the background. Verify Data Appeared After the initial sync completes: 1. Go to your app's Analytics Dashboard 2. Check the Partner Metrics section 3. You should see: - Revenue charts - Customer counts - MRR tracking - Subscription metrics Managing Your Connection Manual Sync Options After configuration, two sync options appear: Incremental Sync - Imports only new/changed data - Faster (a few minutes) - Use for regular updates - Click the "Incremental Sync" button Full Sync - Re-imports all historical data - Slower (same as initial sync) - Use if data looks incorrect - Click the "Full Sync" button - Requires confirmation (it deletes existing data first) Automatic Syncing Once connected, Ranksy automatically syncs: - Daily: Overnight (typically 2-3 AM) - Incremental: Only new/changed data - No action needed: It just works! Update Credentials If you need to change credentials: 1. Go to your app Settings 2. Update the fields 3. Click "Save Configuration" 4. New sync starts automatically Disconnect To disconnect the Partner API: 1. Go to your app Settings 2. Find the Partner API section 3. Click "Disconnect" 4. Confirm the disconnection 5. Historical data is preserved for 90 days Troubleshooting Error: "Invalid Organization ID" Fix: - Double-check you copied the complete number - Make sure there are no spaces before/after - Verify it's the Organization ID, not the App ID - Try copying it again from Shopify Error: "Invalid API Key" Fix: - The token is case-sensitive - copy it exactly - No spaces at the beginning or end - Re-copy the Access token from your Partner API client (Settings → Partner API clients → your client → Credentials → Show) — it's viewable anytime - Make sure View financials and Manage apps are both ticked on the API client's permissions Error: "App Not Found" Fix: - Verify the App ID is correct - Make sure it's the App ID, not Organization ID - Check the URL format in Partner Dashboard matches partners.shopify.com/ORG_ID/apps/APP_ID - Ensure you have permissions for this app Sync Stuck or Taking Too Long What to try: - Large apps can take 2-4 hours for initial sync - Check the sync status on Settings page - Wait at least 4 hours before troubleshooting - Try clicking "Full Sync" if stuck - Contact support if stuck for more than 6 hours Data Doesn't Match Partner Dashboard Fix: - Click "Full Sync" to refresh all data - Check that date ranges match exactly - Some metrics are calculated differently (we use different time zones or aggregation methods) - If still mismatched after full sync, contact support Security & Privacy How Ranksy Handles Your Data Credentials: - Encrypted at rest (AES-256) - Encrypted in transit (TLS/SSL) - Never stored in plain text - Access is logged and monitored Data Access: - Read-only access to your Partner data - We NEVER modify your Shopify data - Your data stays yours - Isolated per account Compliance: - GDPR compliant - SOC 2 practices followed - Regular security audits - Data processing agreements available FAQ Q: Is the Partner API free to use? A: Yes! Shopify's Partner API is free within reasonable usage limits. Q: Will this affect my Shopify billing? A: No. Connecting the Partner API doesn't change your Shopify costs. Q: Can I connect multiple apps? A: Yes! Connect each app separately using the same or different credentials. Q: What if my access token leaks? A: Open your Partner API client and click Generate secondary token to rotate the access token (or delete the client to revoke access entirely), then paste the new token into Ranksy. Q: Can I pause syncing? A: Yes. Disconnect the integration in Settings. You can reconnect anytime. Q: How often should I manually sync? A: You don't need to! Automatic daily syncs keep your data current. Only use manual sync if you need real-time data or troubleshooting. Next Steps Now that Partner API is connected: - Connect Google BigQuery - Add traffic and session data - Explore Partner Metrics - Understand your revenue analytics - View Customer Management - See your complete customer list - Understand Attribution - Learn which channels drive revenue Need help? Contact [email protected] or use the chat widget. Include your app name and any error messages.

Connect BigQuery with Service Account

How to Connect Google BigQuery with Service Account This guide shows you how to connect BigQuery to Ranksy using our service account. This method is simpler than OAuth - you just grant access to our service account in your Google Cloud project. What You'll Get Once connected, Ranksy imports your GA4 data and shows: - Traffic Sources: Where visitors come from - Pageviews: How many people view your app listing - Sessions: Complete user journeys - Geographic Data: User locations - Device Data: Mobile vs desktop traffic - Click Events: User interactions - Conversion Tracking: From view to install - Attribution: Which channels drive customers Prerequisites Before you start, make sure you have: - Google Analytics 4 (GA4) tracking your Shopify app - GA4 linked to BigQuery with data export enabled - At least 24 hours of exported data in BigQuery - Access to Google Cloud Console for your project Don't have BigQuery export set up yet? See our Set Up GA4 BigQuery Export guide first. Step 1: Grant Access to Ranksy Service Account in Google Cloud IAM In this step, you'll add the Ranksy service account to your Google Cloud project and give it permission to read your BigQuery data. Video Tutorial https://videos.ranksyapp.com/videos/add-ranksy-service-account-to-big-query.mp4 Written Instructions 1.1 Open Google Cloud Console 1. Go to console.cloud.google.com 2. Make sure you're signed into the Google account that owns the BigQuery project 3. Select your project from the dropdown at the top of the page 1.2 Navigate to IAM & Admin 1. Click the hamburger menu (☰) in the top left 2. Scroll down and click IAM & Admin 3. Click IAM in the submenu 1.3 Add the Ranksy Service Account 1. Click the + GRANT ACCESS button at the top 2. In the "New principals" field, enter the Ranksy service account email: [email protected] 3. Click in the "Select a role" dropdown 1.4 Assign Required Roles You need to add two roles to the service account: First Role - BigQuery Data Viewer: 1. In the role dropdown, type "BigQuery Data Viewer" 2. Select BigQuery Data Viewer from the list Second Role - BigQuery Job User: 1. Click + ADD ANOTHER ROLE 2. Type "BigQuery Job User" 3. Select BigQuery Job User from the list 1.5 Save the Configuration 1. Review your settings: - Principal: [email protected] - Roles: BigQuery Data Viewer, BigQuery Job User 2. Click SAVE You should see the Ranksy service account appear in your IAM members list. Why These Roles? | Role | Purpose | |------|---------| | BigQuery Data Viewer | Allows reading data from your BigQuery tables | | BigQuery Job User | Allows running queries against your data | These are read-only permissions. Ranksy cannot modify, delete, or write to your BigQuery data. Step 2: Connect BigQuery in Ranksy Now that you've granted access, enter your project details in Ranksy to complete the connection. Video Tutorial https://videos.ranksyapp.com/videos/add-bigquery-project-details-to-ranksy.mp4 Written Instructions 2.1 Navigate to App Settings 1. Log into Ranksy 2. Click on your profile/name in the bottom left of the sidebar 3. Click Manage Apps from the dropdown menu 4. Click on your app's row to open its settings page 2.2 Find the BigQuery Section Scroll down to the Google BigQuery integration card. 2.3 Enter Your Project Details Google Cloud Project ID: 1. This is your Google Cloud project identifier 2. Find it in Google Cloud Console at the top of the page (e.g., my-company-analytics) 3. Enter it in the "Google Cloud Project ID" field BigQuery Dataset ID: 1. This is where GA4 exports your data 2. The format is analytics_XXXXXXXXX where X's are your GA4 property ID 3. Enter it in the "BigQuery Dataset ID" field Example configuration: - Project ID: my-company-analytics - Dataset ID: analytics_123456789 2.4 Save and Import 1. Click Save Configuration & Import Data 2. Ranksy will: - Validate the connection - Start importing your historical data - Show a success message Finding Your Dataset ID If you're not sure what your dataset ID is: 1. Go to console.cloud.google.com 2. Navigate to BigQuery (in the sidebar or search for it) 3. In the left panel, expand your project 4. Look for a dataset named analytics_XXXXXXXXX 5. The dataset name is your Dataset ID What Happens After Connection Initial Import After saving your configuration: - Ranksy begins importing your historical GA4 data - Import duration depends on data volume (typically 15-60 minutes) - You can close the page - import continues in the background Automatic Updates Once connected, Ranksy automatically: - Daily: Imports new data each morning - Every 4 hours: Checks for intraday updates - No manual action required! View Your Data After import completes, explore your data: - Traffic Analytics: See where your visitors come from - Attribution: Understand which channels drive installs - Analytics Dashboard: Get a complete overview Troubleshooting Error: "Access denied" or "Permission denied" The service account doesn't have access to your project. Fix: 1. Go back to Google Cloud Console → IAM & Admin → IAM 2. Verify the Ranksy service account is listed 3. Check it has both BigQuery Data Viewer and BigQuery Job User roles 4. If missing, click the pencil icon to edit and add the missing role Error: "Dataset not found" The dataset ID is incorrect or doesn't exist. Fix: 1. Go to BigQuery in Google Cloud Console 2. Verify the dataset analytics_XXXXXXXXX exists 3. Copy the exact dataset name and paste it in Ranksy 4. Make sure there are no typos or extra spaces Error: "Project not found" The project ID is incorrect. Fix: 1. Go to Google Cloud Console 2. Look at the project selector at the top - copy the project ID (not the name) 3. Enter the exact project ID in Ranksy Import Takes Too Long Large datasets can take time to import. What to expect: - 7 days of data: 15-30 minutes - 30 days of data: 30-60 minutes - 1 year of data: 2-4 hours If import hasn't completed after 6 hours, contact support. No Data Shows After Import Check these: 1. Verify GA4 is actually tracking your app (check Google Analytics) 2. Confirm BigQuery export has data (check tables in BigQuery console) 3. Make sure you selected the correct date range in Ranksy Security & Privacy What We Access Ranksy only reads your GA4 event data from BigQuery. We cannot: - Modify your data - Delete tables or datasets - Access other Google services - See data from other projects Data Handling - All data is encrypted in transit (TLS/SSL) - Stored encrypted at rest (AES-256) - Isolated per account - GDPR compliant FAQ Q: Why use service account instead of OAuth? A: Service account is simpler - no login popups, no token expiration, more reliable long-term connection. Q: Can multiple team members use this? A: Yes! Once the service account has access, any team member in Ranksy can view the data. Q: What if I remove the service account later? A: Ranksy will no longer be able to import new data, but existing imported data remains. Q: Does this cost money? A: BigQuery has a free tier (1 TB queries/month, 10 GB storage). Most apps stay within free limits. Q: Can I use both OAuth and service account? A: No, you use one or the other. Service account is recommended for most users. Next Steps Now that BigQuery is connected: - View Traffic Analytics - See where your visitors come from - Explore Attribution - Understand your customer journey - Check Analytics Dashboard - Get the full picture Need help? Contact [email protected] or use the chat widget. Include your app name and any error messages you see.

Set Up GA4 BigQuery Export

How to Set Up GA4 BigQuery Export https://videos.ranksyapp.com/videos/link-ga4-bigquery-export.mp4 This guide walks you through connecting Google Analytics 4 (GA4) to BigQuery so you can analyze your Shopify app's traffic data in Ranksy. Why You Need This BigQuery export enables Ranksy to access your GA4 data and show you: - Traffic Sources: Where your app listing visitors come from - Conversion Funnels: How users move from view to install - Attribution Data: Which marketing channels drive installs - Session Analytics: Complete user journey tracking Without BigQuery export, this data stays locked inside Google Analytics. Before You Start Make sure you have: - GA4 tracking set up on your Shopify app listing - A Google account with access to both GA4 and Google Cloud - 10-15 minutes to complete the setup Step 1: Create a Google Cloud Project If you don't already have a Google Cloud project, create one now. 1.1 Open Google Cloud Console 1. Go to console.cloud.google.com 2. Sign in with your Google account 1.2 Create a New Project 1. Click the project dropdown at the top of the page 2. Click New Project 3. Enter a project name (e.g., my-app-analytics) 4. Click Create 5. Wait for the project to be created (takes a few seconds) 1.3 Select Your Project 1. Click the project dropdown again 2. Select your newly created project 3. You should see the project name at the top of the page Step 2: Enable Billing BigQuery requires billing to be enabled, but don't worry - most usage stays within the free tier. Free Tier Includes: - 1 TB of query processing per month - 10 GB of storage - Most Shopify apps never exceed these limits 2.1 Set Up Billing 1. In Google Cloud Console, click the hamburger menu (☰) 2. Go to Billing 3. Click Link a billing account (or create one if you don't have one) 4. Follow the prompts to add a payment method 2.2 Set Budget Alerts (Recommended) Protect yourself from unexpected charges: 1. Go to Billing → Budgets & alerts 2. Click Create Budget 3. Set a budget amount (e.g., $1 or $5) 4. Enable email alerts at 50%, 90%, and 100% 5. Click Finish You'll be notified if you approach your budget (which is unlikely for most apps). Step 3: Link GA4 to BigQuery Now connect your Google Analytics 4 property to BigQuery. 3.1 Open GA4 Admin 1. Go to analytics.google.com 2. Select your GA4 property (the one tracking your app) 3. Click Admin (gear icon in the bottom left) 3.2 Find BigQuery Links 1. In the Property column (middle column), scroll down 2. Click BigQuery Links under "Product Links" 3.3 Create the Link 1. Click Link 2. Click Choose a BigQuery project 3. Select your Google Cloud project from the list 4. Click Confirm 5. Click Next 3.4 Configure Data Streams 1. Select which data streams to export (usually just one - your app tracking) 2. Click Next 3.5 Configure Export Settings Choose your export options: Frequency: - Daily - Data exports once per day (recommended, free) - Streaming - Near real-time export (costs more, usually not needed) Recommended settings: - Enable Daily export - Enable Streaming only if you need real-time data and are OK with higher costs Include advertising identifiers: - Leave unchecked unless you specifically need this data 3.6 Complete the Link 1. Review your settings 2. Click Submit 3. You'll see a confirmation that the link was created Step 4: Wait for Data Export After linking, GA4 will start exporting data to BigQuery. Timeline - First export: Within 24 hours - Daily tables: Created each morning (named events_YYYYMMDD) - Intraday tables: Created throughout the day if streaming is enabled Verify the Export After 24 hours, check that data is flowing: 1. Go to console.cloud.google.com 2. Select your project 3. Go to BigQuery (search for it or find in the menu) 4. In the left panel, expand your project 5. Look for a dataset named analytics_XXXXXXXXX (where X's are your GA4 property ID) 6. Expand the dataset - you should see tables like: - events_20250118 (daily table) - events_intraday_20250118 (if streaming enabled) If you see these tables, your export is working. Step 5: Find Your Dataset Information You'll need these details to connect Ranksy: Project ID 1. In Google Cloud Console, look at the top of the page 2. Your project ID is shown (e.g., my-app-analytics-12345) 3. Note: This might differ from your project name Dataset ID 1. In BigQuery, expand your project 2. The dataset name is your Dataset ID (e.g., analytics_123456789) 3. This is the analytics_ prefix followed by your GA4 property ID Troubleshooting No Dataset Appears After 24 Hours Check these: 1. GA4 is collecting data: Go to GA4 → Reports → Realtime to verify events are being tracked 2. Link is active: Go to GA4 → Admin → BigQuery Links and verify the link shows "Active" 3. Correct project: Make sure you're looking at the right Google Cloud project 4. Billing enabled: BigQuery requires billing - check it's set up "Permission Denied" Errors Fix: 1. Make sure you're signed into the correct Google account 2. Verify you have Owner or Editor access to the Google Cloud project 3. Try signing out and back in Dataset Name Doesn't Match Expected Format The dataset should be named analytics_XXXXXXXXX. If it's different: 1. You might have multiple GA4 properties linked 2. Check your GA4 property ID (Admin → Property Settings) and match it to the dataset number Data is Missing or Incomplete Possible causes: 1. Too soon: Wait a full 24-48 hours for the first export 2. GA4 not tracking: Verify your GA4 tracking code is installed correctly 3. Wrong data stream: Make sure you selected the correct data stream when linking Important Notes Data Timing - BigQuery export is not retroactive - it only exports data from the moment you create the link - Historical data in GA4 will not appear in BigQuery - Set up the export as early as possible to capture more data Cost Considerations Typical costs for Shopify apps: | Usage Level | Monthly Cost | |-------------|--------------| | Low traffic app | $0 (free tier) | | Medium traffic app | $0-5 | | High traffic app | $5-20 | Most apps stay well within the free tier. Best Practice: Dedicated GA4 Property Use a dedicated GA4 property just for your Shopify app listing. This: - Keeps data clean and focused - Reduces BigQuery storage and query costs - Makes analysis easier in Ranksy Don't mix your app store tracking with other website tracking. Next Steps Now that BigQuery export is set up: 1. Wait 24 hours for data to appear 2. Connect BigQuery to Ranksy - Grant Ranksy access to your data 3. Start analyzing - View traffic, attribution, and conversion data Need help? Contact [email protected] or use the chat widget. Include your GA4 property ID and Google Cloud project name.