import type { GuidePage } from "@/lib/pseo-page-types";

export const guidePages: GuidePage[] = [
  {
    slug: "why-my-qr-code-is-not-scanning",
    title: "Why My QR Code Is Not Scanning",
    description:
      "Fix the most common QR code scanning failures: print size, contrast, blur, damaged quiet zones, and bad landing pages.",
    canonicalPath: "/guide/why-my-qr-code-is-not-scanning",
    targetKeyword: "why my qr code is not scanning",
    guideType: "problem-solving",
    intentStage: "middle",
    cluster: "guides",
    intro:
      "Most scan failures are not caused by the QR format itself. They are caused by print, contrast, surface finish, or a destination that feels broken after the scan.",
    quickAnswer:
      "If a QR code is not scanning, check size, contrast, quiet zone, print sharpness, surface glare, and whether the destination page actually loads fast on mobile.",
    symptoms: [
      "Phones detect the code inconsistently or not at all",
      "The code scans in one lighting condition but fails in another",
      "Users say the QR works for some devices but not others",
    ],
    howToSteps: [
      "Check whether the printed code is large enough for the expected scanning distance.",
      "Verify strong dark-on-light contrast and an intact quiet zone around the code.",
      "Test for glare, reflection, blur, or warped print surfaces.",
      "Scan on both iPhone and Android using the actual production asset.",
      "Confirm the landing page loads quickly and does not feel broken after the scan.",
    ],
    keyTakeaways: [
      "Most failures come from physical execution, not from the QR concept.",
      "A QR code that technically scans but leads to a slow or broken page still fails in practice.",
      "Production testing on real materials matters more than on-screen previews.",
    ],
    checklist: {
      title: "Scan troubleshooting checklist",
      items: [
        "Minimum size appropriate to distance and surface",
        "Dark modules on a light background",
        "No cropped quiet zone",
        "No glossy glare or severe print blur",
        "Fast mobile landing page",
      ],
    },
    faq: [
      {
        question: "Can a QR code be too small to scan?",
        answer: "Yes. Small size is one of the most common reasons scans fail on real printed materials.",
      },
      {
        question: "Does glossy paper affect scanning?",
        answer: "Yes. Reflections can make a technically valid QR code unreliable in practice.",
      },
      {
        question: "Why does it scan on one phone but not another?",
        answer: "Camera quality, focus speed, and lighting tolerance vary across devices, which is why production testing should cover both major mobile platforms.",
      },
    ],
    primaryCta: {
      href: "/custom-qr-code-generator",
      label: "Create a cleaner QR",
    },
    secondaryCta: {
      href: "/guide/qr-code-print-size",
      label: "Check print size guidance",
    },
    relatedLinks: [
      {
        href: "/guide/qr-code-print-size",
        title: "QR Code Print Size",
        description: "The most common companion problem to scan failures.",
      },
      {
        href: "/compare/dynamic-vs-static-qr-codes",
        title: "Dynamic vs Static QR Codes",
        description: "Helpful when the scan issue is actually a stale destination problem.",
      },
      {
        href: "/custom-qr-code-generator",
        title: "Custom QR Code Generator",
        description: "Commercial page for designing scannable branded QR assets.",
      },
    ],
  },
  {
    slug: "qr-code-print-size",
    title: "QR Code Print Size Guide",
    description:
      "Learn the right QR code print sizes for flyers, tables, packaging, posters, and labels so users can scan reliably.",
    canonicalPath: "/guide/qr-code-print-size",
    targetKeyword: "qr code print size",
    guideType: "problem-solving",
    intentStage: "middle",
    cluster: "guides",
    intro:
      "Print size is one of the few QR decisions that directly affects scan success before the user even reaches the landing page.",
    quickAnswer:
      "The right QR code print size depends on scan distance, surface, and lighting. For close-range scans, the code still needs enough size, contrast, and quiet zone to survive real-world conditions.",
    symptoms: [
      "Scans fail more often on packaging or posters than on screen",
      "A QR code works up close but not from normal user distance",
      "Design teams shrink the QR too far to preserve layout aesthetics",
    ],
    howToSteps: [
      "Start from the real scan distance instead of the design canvas.",
      "Choose a QR size that remains legible after printing, trimming, and finishing.",
      "Protect the quiet zone and avoid pushing text or shapes too close to the code.",
      "Test the asset at actual production size on the final material.",
      "Increase the size if the environment includes glare, motion, or low light.",
    ],
    keyTakeaways: [
      "QR sizing is a production problem, not just a design preference.",
      "Distance, glare, and material finish should influence size decisions early.",
      "Testing at final production size is the only trustworthy validation.",
    ],
    checklist: {
      title: "Print-size review",
      items: [
        "Confirm normal scanning distance",
        "Preserve quiet zone",
        "Check final material finish",
        "Test on mobile in realistic light",
        "Do not shrink only for layout aesthetics",
      ],
    },
    faq: [
      {
        question: "Does the same QR code size work for every surface?",
        answer: "No. Packaging, flyers, posters, and table signage often need different size decisions because the scan distance and surface conditions differ.",
      },
      {
        question: "Why is print-size guidance so important?",
        answer: "Because a QR code that looks fine in the design tool can still fail in real-world scanning conditions.",
      },
      {
        question: "Should I increase size for glossy materials?",
        answer: "Usually yes, because reflections reduce scanning tolerance.",
      },
    ],
    primaryCta: {
      href: "/custom-qr-code-generator",
      label: "Generate a print-ready QR",
    },
    secondaryCta: {
      href: "/guide/why-my-qr-code-is-not-scanning",
      label: "Troubleshoot scan failures",
    },
    relatedLinks: [
      {
        href: "/use-cases/flyer-qr-codes",
        title: "Flyer QR Codes",
        description: "Use-case page where print-size discipline matters immediately.",
      },
      {
        href: "/use-cases/packaging-qr-codes",
        title: "Packaging QR Codes",
        description: "Practical cluster page for small-surface QR production.",
      },
      {
        href: "/compare/bulk-qr-generator-vs-single-qr-generator",
        title: "Bulk vs Single QR Generation",
        description: "Helpful when print production is scaling across many assets.",
      },
    ],
  },
  {
    slug: "how-to-track-qr-code-scans",
    title: "How to Track QR Code Scans",
    description:
      "Set up trackable QR codes, naming conventions, and campaign-friendly reporting so offline scans become measurable.",
    canonicalPath: "/guide/how-to-track-qr-code-scans",
    targetKeyword: "how to track qr code scans",
    guideType: "problem-solving",
    intentStage: "bottom",
    cluster: "guides",
    intro:
      "Tracking QR scans is not only about counting taps. It is about preserving campaign context so the scan means something later.",
    quickAnswer:
      "To track QR code scans properly, use dynamic QR codes, structured campaign naming, and destinations that preserve attribution context across placements and experiments.",
    howToSteps: [
      "Use a dynamic QR workflow so the destination is measurable and editable.",
      "Apply naming conventions by campaign, surface, and location.",
      "Separate placements instead of routing every printed asset into one generic code.",
      "Review scan patterns by time, device, and workflow context.",
      "Connect scan data to your broader analytics and reporting conventions.",
    ],
    keyTakeaways: [
      "Tracking without naming discipline creates data noise.",
      "Separate placements if you want useful reporting later.",
      "The business value of QR codes increases when offline scans can be tied to decisions.",
    ],
    checklist: {
      title: "Tracking setup checklist",
      items: [
        "Use dynamic QR codes",
        "Adopt campaign naming standards",
        "Split major placements",
        "Review device and time patterns",
        "Align with reporting expectations",
      ],
    },
    faq: [
      {
        question: "Can static QR codes be tracked well?",
        answer: "Not as well as dynamic QR workflows, especially when you need editability and cleaner campaign context.",
      },
      {
        question: "Should each flyer or poster have its own QR code?",
        answer: "Not always, but major placement differences should usually be separated if the reporting needs are meaningful.",
      },
      {
        question: "What is the biggest mistake in QR tracking?",
        answer: "Treating every offline surface as one undifferentiated source.",
      },
    ],
    primaryCta: {
      href: "/qr-code-tracking",
      label: "See QR tracking",
    },
    secondaryCta: {
      href: "/compare/dynamic-vs-static-qr-codes",
      label: "Compare dynamic vs static",
    },
    relatedLinks: [
      {
        href: "/qr-code-analytics",
        title: "QR Code Analytics",
        description: "Commercial analytics page aligned to scan reporting use cases.",
      },
      {
        href: "/compare/free-vs-paid-qr-code-generator",
        title: "Free vs Paid QR Generator",
        description: "Useful when the tracking need is what changes the purchase decision.",
      },
      {
        href: "/use-cases/flyer-qr-codes",
        title: "Flyer QR Codes",
        description: "A high-fit use case for measurable offline campaign tracking.",
      },
    ],
  },
  {
    slug: "qr-code-gdpr",
    title: "QR Codes and GDPR",
    description:
      "Understand how QR code tracking intersects with GDPR and what privacy-safe analytics design looks like for business use.",
    canonicalPath: "/guide/qr-code-gdpr",
    targetKeyword: "qr code gdpr",
    guideType: "strategic",
    intentStage: "middle",
    cluster: "guides",
    intro:
      "GDPR questions appear early in B2B QR evaluations because scan tracking can easily turn into a trust issue if handled poorly.",
    quickAnswer:
      "QR codes can be used in a GDPR-aware way when the analytics model minimizes personal data, uses privacy-safe tracking decisions, and communicates the workflow clearly.",
    howToSteps: [
      "Review what data your QR workflow actually collects after a scan.",
      "Minimize or transform personal identifiers wherever possible.",
      "Separate operational analytics from unnecessary personal profiling.",
      "Document the business purpose behind scan measurement.",
      "Make privacy posture part of the buying and implementation conversation.",
    ],
    keyTakeaways: [
      "Privacy posture can be a conversion advantage, not just a compliance burden.",
      "GDPR concerns show up early in B2B evaluation for trackable QR workflows.",
      "The strongest approach is data minimization and clear communication.",
    ],
    faq: [
      {
        question: "Are QR codes themselves a GDPR problem?",
        answer: "The QR image itself is not usually the issue. The real concern is the data collected after the scan.",
      },
      {
        question: "Why is GDPR a differentiator for QR Master?",
        answer: "Because QR Master already has a privacy-first product story that can be turned into a clearer buying advantage.",
      },
      {
        question: "What should buyers ask vendors about QR tracking?",
        answer: "What data is collected, how it is minimized, and how the analytics workflow is explained and governed.",
      },
    ],
    primaryCta: {
      href: "/qr-code-tracking",
      label: "See privacy-first tracking",
    },
    secondaryCta: {
      href: "/compare/beaconstac-alternative",
      label: "See comparison pages",
    },
    relatedLinks: [
      {
        href: "/qr-code-analytics",
        title: "QR Code Analytics",
        description: "Commercial page for the measurement side of the privacy conversation.",
      },
      {
        href: "/guide/how-to-track-qr-code-scans",
        title: "How to Track QR Code Scans",
        description: "Practical guide to pair with the policy and trust angle.",
      },
      {
        href: "/compare/free-vs-paid-qr-code-generator",
        title: "Free vs Paid QR Generator",
        description: "Useful when buyers are weighing business-grade control against simple free tools.",
      },
    ],
  },
  {
    slug: "how-to-create-a-vcard-qr-code",
    title: "How to Create a vCard QR Code",
    description:
      "Create a vCard QR code that helps people save contact details instantly and still fits business-card and networking workflows.",
    canonicalPath: "/guide/how-to-create-a-vcard-qr-code",
    targetKeyword: "how to create a vcard qr code",
    guideType: "problem-solving",
    intentStage: "bottom",
    cluster: "guides",
    intro:
      "vCard QR creation is often easy in theory but weak in practice when the saved contact flow or the printed asset is not thought through.",
    quickAnswer:
      "To create a good vCard QR code, choose the right contact fields, keep the scan experience focused on saving details fast, and test it on both iPhone and Android before printing.",
    howToSteps: [
      "Choose the exact contact fields you want saved after the scan.",
      "Generate the vCard QR with a clear save-contact workflow.",
      "Keep the printed CTA focused on one next action.",
      "Test cross-device behavior before using the QR on business cards or badges.",
      "Use dynamic management if the profile destination may evolve later.",
    ],
    keyTakeaways: [
      "The best vCard QR is optimized for the save-contact action, not for stuffing every possible detail into one scan.",
      "Cross-device testing matters because contact-saving behavior differs slightly between platforms.",
      "Business-card workflows benefit when the QR destination can evolve later.",
    ],
    faq: [
      {
        question: "What should a vCard QR include?",
        answer: "Only the fields that materially improve the save-contact experience, such as name, phone, email, role, and a clear business context.",
      },
      {
        question: "Should a vCard QR be static or dynamic?",
        answer: "Static can work for direct contact saving, but dynamic is useful if the underlying profile or next step may change later.",
      },
      {
        question: "Where does this guide convert best?",
        answer: "On business cards, badges, and networking workflows where the scan intent is already strong.",
      },
    ],
    primaryCta: {
      href: "/tools/vcard-qr-code",
      label: "Create a vCard QR",
    },
    secondaryCta: {
      href: "/use-cases/business-card-qr-codes",
      label: "See business-card workflows",
    },
    relatedLinks: [
      {
        href: "/use-cases/business-card-qr-codes",
        title: "Business Card QR Codes",
        description: "The strongest adjacent cluster page for this guide.",
      },
      {
        href: "/compare/dynamic-vs-static-qr-codes",
        title: "Dynamic vs Static QR Codes",
        description: "Useful when buyers are deciding how permanent the contact workflow should be.",
      },
      {
        href: "/tools/vcard-qr-code",
        title: "vCard QR Code Tool",
        description: "Commercial parent tool page for direct creation intent.",
      },
    ],
  },
  {
    slug: "how-to-use-utm-with-qr-codes",
    title: "How to Use UTM Parameters with QR Codes",
    description:
      "Use UTM parameters with QR codes so offline scans can be grouped, attributed, and compared more cleanly in campaign analysis.",
    canonicalPath: "/guide/how-to-use-utm-with-qr-codes",
    targetKeyword: "how to use utm with qr codes",
    guideType: "problem-solving",
    intentStage: "middle",
    cluster: "guides",
    intro:
      "UTM setup is where many offline QR campaigns either become measurable or collapse into data ambiguity.",
    quickAnswer:
      "Use UTM parameters with QR codes by standardizing campaign naming, separating major surfaces, and keeping the destination structure consistent enough to support reporting later.",
    howToSteps: [
      "Define a naming standard for campaign, surface, and placement.",
      "Apply UTM logic consistently across related QR assets.",
      "Separate materially different placements instead of collapsing them together.",
      "Validate that the destination preserves campaign attribution as expected.",
      "Review performance in the context of the full QR campaign, not just raw scan totals.",
    ],
    keyTakeaways: [
      "UTMs are only useful when naming discipline is consistent.",
      "Offline campaign attribution becomes much more useful when placements are separated on purpose.",
      "This guide converts best when paired with tracking and analytics pages.",
    ],
    faq: [
      {
        question: "Do all QR codes need UTMs?",
        answer: "No. UTMs matter most when campaign attribution and placement comparison are part of the goal.",
      },
      {
        question: "What is the most common UTM mistake with QR codes?",
        answer: "Using inconsistent naming so the campaign data becomes too noisy to compare later.",
      },
      {
        question: "Should each physical surface have its own UTM setup?",
        answer: "Major placement differences usually should, especially when performance comparison matters.",
      },
    ],
    primaryCta: {
      href: "/qr-code-tracking",
      label: "Build a trackable QR",
    },
    secondaryCta: {
      href: "/qr-code-analytics",
      label: "See analytics workflows",
    },
    relatedLinks: [
      {
        href: "/guide/how-to-track-qr-code-scans",
        title: "How to Track QR Code Scans",
        description: "Natural parent guide for the broader measurement question.",
      },
      {
        href: "/use-cases/flyer-qr-codes",
        title: "Flyer QR Codes",
        description: "A high-fit offline campaign use case for UTM discipline.",
      },
      {
        href: "/qr-code-for-marketing-campaigns",
        title: "QR Codes for Marketing Campaigns",
        description: "Commercial cluster page for attribution-focused campaign use.",
      },
    ],
  },
  {
    slug: "qr-code-security-best-practices",
    title: "QR Code Security Best Practices",
    description:
      "Reduce QR-code security risk with safer redirect practices, trusted destinations, and operational checks for printed assets.",
    canonicalPath: "/guide/qr-code-security-best-practices",
    targetKeyword: "qr code security best practices",
    guideType: "strategic",
    intentStage: "middle",
    cluster: "guides",
    intro:
      "Security is a trust issue in QR adoption because users cannot inspect the destination before they scan as easily as they can with visible URLs.",
    quickAnswer:
      "QR code security depends on trusted destinations, transparent workflows, tamper-aware physical deployment, and safer redirect management after the code is printed.",
    howToSteps: [
      "Use trustworthy domains and avoid suspicious redirect chains.",
      "Inspect physical placements for tampering or sticker overlays.",
      "Keep the post-scan destination consistent with user expectation.",
      "Review the workflow for unnecessary security surprises after the scan.",
      "Make trust and safety part of the deployment process, not an afterthought.",
    ],
    keyTakeaways: [
      "Security is about both the digital destination and the physical deployment.",
      "A trustworthy user experience helps both adoption and brand protection.",
      "Security content also supports comparison and conversion pages where trust is a buying factor.",
    ],
    faq: [
      {
        question: "Can QR codes themselves be hacked?",
        answer: "The code image is not the main issue. The risk usually comes from malicious destinations or tampered physical placements.",
      },
      {
        question: "Why do security concerns matter for commercial QR pages?",
        answer: "Because trust directly affects scan willingness and vendor selection.",
      },
      {
        question: "How should teams reduce QR-code tampering risk?",
        answer: "Use regular physical checks, trustworthy domains, and deployment processes that make changes easy to detect.",
      },
    ],
    primaryCta: {
      href: "/dynamic-qr-code-generator",
      label: "Use a trusted QR workflow",
    },
    secondaryCta: {
      href: "/guide/qr-code-gdpr",
      label: "Review privacy guidance",
    },
    relatedLinks: [
      {
        href: "/compare/beaconstac-alternative",
        title: "Beaconstac Alternative",
        description: "Trust and governance are often part of the comparison motion.",
      },
      {
        href: "/guide/why-my-qr-code-is-not-scanning",
        title: "Why My QR Code Is Not Scanning",
        description: "Operational reliability and trust often intersect in real deployments.",
      },
      {
        href: "/qr-code-tracking",
        title: "QR Code Tracking",
        description: "Commercial page connected to trustworthy managed workflows.",
      },
    ],
  },
  {
    slug: "dynamic-qr-code-best-practices",
    title: "Dynamic QR Code Best Practices",
    description:
      "Use dynamic QR codes the right way across print, tracking, naming, and post-print change management.",
    canonicalPath: "/guide/dynamic-qr-code-best-practices",
    targetKeyword: "dynamic qr code best practices",
    guideType: "strategic",
    intentStage: "middle",
    cluster: "guides",
    intro:
      "Dynamic QR codes create flexibility, but that flexibility only becomes a business advantage when the workflow is designed on purpose.",
    quickAnswer:
      "The best dynamic QR workflows use clear naming, stable print placement, measurable destinations, and disciplined update management after the code is in circulation.",
    howToSteps: [
      "Name codes by campaign, workflow, or printed surface before launch.",
      "Choose stable print placements that should survive destination changes.",
      "Separate major placements if the reporting value justifies it.",
      "Use clear CTA language on the asset so the scan intent is obvious.",
      "Treat destination updates as an operational process, not an ad hoc fix.",
    ],
    keyTakeaways: [
      "Dynamic QR codes are most valuable when paired with naming and campaign discipline.",
      "Stable print plus flexible destination is the core operational advantage.",
      "This topic naturally links commercial, guide, and use-case clusters together.",
    ],
    faq: [
      {
        question: "What is the biggest mistake with dynamic QR codes?",
        answer: "Creating them without a naming, placement, or update process, which makes later reporting and operations messy.",
      },
      {
        question: "Should every QR code be dynamic?",
        answer: "No, but most business-critical printed workflows benefit from dynamic management.",
      },
      {
        question: "Why is this guide strategic instead of purely tactical?",
        answer: "Because it shapes how a business structures QR workflows across multiple campaigns and surfaces.",
      },
    ],
    primaryCta: {
      href: "/dynamic-qr-code-generator",
      label: "Create a dynamic QR",
    },
    secondaryCta: {
      href: "/compare/dynamic-vs-static-qr-codes",
      label: "See the comparison",
    },
    relatedLinks: [
      {
        href: "/compare/dynamic-vs-static-qr-codes",
        title: "Dynamic vs Static QR Codes",
        description: "Core comparison page for this guide's main concept.",
      },
      {
        href: "/guide/how-to-track-qr-code-scans",
        title: "How to Track QR Code Scans",
        description: "The measurement counterpart to dynamic workflow setup.",
      },
      {
        href: "/dynamic-qr-code-generator",
        title: "Dynamic QR Code Generator",
        description: "Commercial parent for immediate product action.",
      },
    ],
  },
];

export const guidePagesMap = Object.fromEntries(
  guidePages.map((page) => [page.slug, page]),
);

export function getGuidePage(slug: string): GuidePage | undefined {
  return guidePagesMap[slug];
}
