If you’re setting up rules in Bunchball and things aren’t working the way you expect, you’re not alone. Rules are powerful, but they’re also finicky. Maybe points aren’t being awarded, badges refuse to trigger, or your users are stuck at Level 1 despite their best efforts. This guide is for admins, program managers, or anyone responsible for making Bunchball actually do what it promises.
Let’s cut through the confusion and get your rules behaving.
Step 1: Confirm the Rule Trigger Is Actually Firing
Most rule headaches start here: Bunchball rules won’t do anything unless the right event hits the system.
- Double-check your event: Is the event you expect actually being sent into Bunchball? Open your analytics or activity logs and look for it.
- Case sensitivity matters: “Login” and “login” are not the same. Spelling and capitalization must match exactly.
- Right event, wrong place: Are you sending the event to the correct Bunchball instance or environment (dev, test, prod)? It's easy to miss this when you have multiple environments.
Pro tip: Manually trigger the event (e.g., by performing the action in your app) and immediately check the activity stream in Bunchball. If nothing shows up, the issue is upstream—fix that before worrying about the rule itself.
Step 2: Review Rule Conditions and Filters
Even if your event lands in Bunchball, your rule conditions might be blocking it.
- User segments: Check if your rule is limited to certain user groups or segments. If you’re testing as the wrong user, the rule won’t fire.
- Date ranges: Some rules are set to only work within specific dates or times. Make sure your rule is “active” and not expired or scheduled for the future.
- One-time vs. repeatable: Is your rule set to only trigger once per user? If you’ve already triggered it in testing, it won’t fire again unless you reset or change the rule.
- Stacked filters: Too many filters (like “User must be in group A and must have completed activity X and must be on level 3”) can make it almost impossible for anyone to qualify. Simplify if you’re troubleshooting.
What to ignore: The “test rule” button is unreliable for complex conditions. Test in the real environment with an actual user account whenever you can.
Step 3: Check Rule Rewards and Actions
Maybe your rule triggers, but the reward doesn’t show up. Here’s what to check:
- Reward type exists: If you’re awarding a badge, does that badge actually exist and is it published? Same for points, levels, or virtual goods.
- Point value typo: Accidentally awarding 0 points is a classic mistake. Double-check the value.
- Conflicting rules: Sometimes, another rule or system is immediately removing or overriding your award (like a “deduct points” rule right after an “award points” rule).
- Hidden rewards: Some rewards don’t show up in the user’s visible profile until after a sync or refresh. Don’t trust the first screen you see.
Step 4: Audit Rule Priority and Order
Bunchball executes rules in a certain order, and rule priority can make or break your logic.
- Rule order matters: If two rules handle the same event but do different things, the one with higher priority (lower number) runs first.
- Mutually exclusive rules: If you have rules that cancel each other out (one adds points, the next removes them), you may end up with a net zero and confused users.
- Disabled rules: This seems obvious, but check that your rule is actually enabled.
Pro tip: When troubleshooting, disable all but the one rule you’re testing. Add others back one at a time. It’s tedious, but it beats chasing ghosts.
Step 5: Inspect Integration Points (APIs, Data Feeds)
If your rules depend on outside data—like user attributes or external events—make sure that data is arriving as expected.
- Stale data: If user info isn’t updating (like levels, group membership, or profile fields), your rules might be working off yesterday’s news.
- API failures: Integration failures don’t always show in the Bunchball UI. Check your logs and error reports for failed API calls or missing data feeds.
- Field mapping: If your rule is looking for “userType” but your data feed calls it “user_type”, nothing’s going to match.
What doesn’t work: Hoping that Bunchball will “figure it out” if your data is inconsistent. It won’t. Map fields carefully and check them regularly.
Step 6: Use Logs, Reports, and Debugging Tools
Don’t fly blind. Bunchball offers logs and reporting, though they’re not always as detailed as you’d hope.
- Activity Stream: This is your go-to for seeing incoming events and which rules triggered. If your event doesn’t show up here, it’s not reaching Bunchball.
- Rule Audit Logs: These show when a rule fired, for whom, and what got awarded.
- Custom Reports: If you’re troubleshooting at scale, set up a report to track rule triggers or reward distributions over time. Spikes or drops can pinpoint when things broke.
Tip: Keep screenshots and notes as you go. If you need to escalate to support, you’ll have a clear trail.
Step 7: Common Pitfalls and Annoyances
Here’s what trips up even experienced admins:
- Caching delays: Sometimes a reward or badge doesn’t show up instantly. Wait a minute, refresh, and check again before changing everything.
- Testing as admin vs. regular user: Admins sometimes bypass rules or have extra permissions. Always test as an ordinary user.
- Too many cooks: Multiple admins changing rules at the same time can overwrite each other’s work. Coordinate and communicate.
- Documentation gaps: Bunchball’s docs are helpful, but not exhaustive. If you’re stuck, check community forums or reach out to support with specifics.
Step 8: When to Ask for Help
If you’ve made it this far and still can’t find the issue:
- Revert to a known good state: Roll back recent changes to see if that fixes things.
- Isolate the problem: Create a new, bare-bones rule (like “award 1 point when user logs in”) and see if it works. If it does, add complexity back piece by piece.
- Contact support: Be ready with event names, user IDs, timestamps, and screenshots. The more specific you can be, the faster they can help.
Keep It Simple, Iterate Often
Rule logic gets messy fast. The best advice? Start simple. Add one condition at a time, test as you go, and don’t try to build the perfect setup in one go. Keep notes of what you change. If something breaks, back up and try a different approach.
Remember: even with all the bells and whistles, Bunchball is only as smart as the rules you feed it. Make your rules clear, your events clean, and your troubleshooting methodical. You’ll save yourself hours of frustration and, honestly, a few headaches. Good luck!