How to Set Up Your Data Integrations

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!