Competition App — User & Admin Guide

Welcome to the Competition App! This guide covers everything you need to know to set up and run competitions for your brand.

What Does This App Do?

The Competition App lets you create and manage promotional competitions and giveaways that your customers can enter. You can run simple single-question competitions (great for quick giveaways and email capture) or detailed form-based competitions with multiple questions.

Customers enter via the public portal — either by scanning a SmartLinks tag, clicking a link, or through an embedded widget on your site.

Getting Started

First-Time Setup

1. Open the admin console — Navigate to admin.html with your collection and app IDs in the URL. You'll see the Competition Management dashboard.

2. General settings — The app supports running multiple competitions at the same time by default. If you only want one active competition at a time, this can be configured in the app settings.

3. Create your first competition — Click the "Create New Competition" button in the top-right corner.

Creating a Competition

The competition editor has four tabs:

Basic Info

• Title — The name your customers will see (e.g., "Summer Giveaway 2025")
• Description — A short summary shown on the competition card
• Competition Type — Choose between:
  • Simple Competition — A single multiple-choice question. Perfect for quick giveaways, polls, or email capture campaigns.
  • Form-based Competition — A multi-field form for detailed entries with custom questions. Use this when you need more than a single question.
• Status — Controls whether the competition accepts entries:
  • Draft — Not visible to customers. Use this while you're still setting things up.
  • Active — Live and accepting entries (within the date window).
  • Closed — No longer accepting entries but still visible.
  • Archived — Hidden from all views.
• Open Date / Close Date — The date window during which entries are accepted. The server enforces these dates automatically — even if someone tries to submit outside the window, it will be rejected.

Contact Fields

Configure which personal details to collect from participants. These are used to create or update contacts in your CRM automatically:

• First name and last name (on by default)
• Email address (on by default — recommended for winner notification)
• Phone number (optional)
• Company name (optional)

Entry Configuration

For simple competitions:

• Question — The multiple-choice question (e.g., "What is your favourite season?")
• Answer Options — Add as many options as you like (minimum 2). Click "Add Option" to add more.
• Allow custom answer — Toggle this on to show an "Other" option where participants can type their own answer.
• Store answer in outcome — When enabled, the selected answer is recorded as the entry's outcome, making it easy to see answer distribution in analytics.

For form-based competitions:

• Form ID — Link to an existing SmartLinks form configuration. The form will be rendered using the SmartLinks Form Renderer.
• Quiz Mode — Optionally enable quiz scoring by selecting which form field contains the answer and what the correct answer is. A quiz score will be calculated and stored with each entry.

Content & Terms

• Rich Content — Additional HTML content displayed on the competition page (e.g., prize descriptions, rules).
• Competition Details — Extra details shown alongside the competition.
• Images — Add image URLs to create a gallery on the competition page.
• Terms and Conditions — Legal text displayed to participants before they submit. Participants must agree to these before entering.

Saving Your Competition

Click "Save Competition" at the bottom of the editor. The system will:

1. Validate all required fields
2. Create the competition definition
3. Set up server-side entry validation (date windows, duplicate prevention)

You'll see a success notification and be returned to the competition list.

Day-to-Day Usage

How Customers Enter

When a customer visits the public portal:

1. If there's only one active competition, they're taken directly to it.
2. If there are multiple active competitions, they see a selection screen and pick one.
3. They fill in their contact details and answer the question (or complete the form).
4. They submit their entry and see a success confirmation.
5. If they've already entered (and duplicate prevention is on), they'll see a message telling them so.

The Competition Widget

A compact widget can be embedded on other SmartLinks pages to promote active competitions. It shows:

• The competition title and status
• A countdown timer to the close date
• An "Enter Competition" button

The widget automatically shows the most recent active competition.

Managing Competitions

Viewing Entries

From the competition list, click the entries icon on any competition to see all submissions. The entries view shows:

• Participant name and email
• Their answer or form data
• Submission timestamp
• Winner status

Selecting a Winner

1. Go to the entries view for a competition
2. Click "Select Random Winner" — the system randomly picks an entry
3. The winner is highlighted and a winner event is recorded
4. You can cancel the winner selection and re-run if needed

Changing Competition Status

You can change a competition's status at any time:

• Set to Active to start accepting entries
• Set to Closed to stop accepting entries
• Set to Archived to hide it from all views

Remember: the open/close dates are also enforced server-side. Even if the status is "Active", entries won't be accepted outside the date window.

Editing a Competition

Click the edit icon on any competition in the list. You can change any field — title, dates, question, options, etc. Changes take effect immediately after saving.

Deleting a Competition

Click the delete icon and confirm. This permanently removes the competition definition and its entry validation rules. This cannot be undone. Existing entry data in the interactions log is preserved.

Import / Bulk Setup

You can create multiple competitions at once by importing a CSV file. Here's a template:

title,description,competitionType,openDate,closeDate,status,question,options,termsAndConditions
"Summer Giveaway","Win a prize pack!",simple,2025-06-01T00:00:00Z,2025-06-30T23:59:59Z,active,"What is your favourite season?","Spring,Summer,Autumn,Winter","Must be 18+"
"Photo Contest","Submit your best photo",complex,2025-07-01T00:00:00Z,2025-07-31T23:59:59Z,draft,,,"Standard T&Cs apply"

Field notes:

• competitionType must be simple or complex
• openDate and closeDate must be ISO 8601 format
• options should be comma-separated within quotes
• Leave question and options empty for complex competitions

Widgets

The CompetitionWidget can be placed on product pages, proof pages, or any SmartLinks portal page. It comes in three sizes:

The widget automatically finds the most recent active competition and displays it. Clicking the entry button navigates the user to the full competition page.

FAQ & Troubleshooting

Why can't customers enter the competition?

Check these things in order:

1. Status — Is the competition set to "Active"?
2. Dates — Is the current date between the open and close dates?
3. Duplicate prevention — Has the customer already entered? Each person can only enter once.

Can I run multiple competitions at the same time?

Yes! By default, multiple competitions can be active simultaneously. Customers will see a selection screen if more than one is available.

What happens when I select a winner?

The system randomly selects one entry and records a "winner" event. The winner's entry is flagged in the entries list. You can cancel and re-run the selection if needed.

Can I change the dates after a competition has started?

Yes, you can edit the dates at any time. The new dates take effect immediately for new entry attempts. Existing entries are not affected.

What's the difference between "simple" and "complex" competitions?

• Simple: One multiple-choice question. Quick to set up, great for giveaways. The answer is stored directly as the entry outcome, making analytics straightforward.
• Complex: A full multi-field form. Use when you need detailed entries (e.g., photo submissions, essay contests, multi-question surveys). Form data is stored in the entry metadata.

How do I see entry statistics?

Entry counts and answer distributions are available through the SmartLinks analytics dashboard. Each competition tracks total entries, answer breakdowns (for simple competitions), and winner status.

Can customers enter from a widget?

The widget shows competition info and a call-to-action button. Clicking it navigates to the full competition page where they can enter. The widget itself doesn't contain the entry form.