Client-Side Collect API Integration Guide

What is Client-side Collect API Integration?

By default, all Zitcha Collect API endpoints require authentication with secure JWT tokens. However, for use cases like browser-based tracking and mobile apps, managing authentication tokens adds complexity.

Therefore, there is the ability to integrate with Collect API's analytics endpoints without authentication, simplifying integration.

When to Use Client-side Integration

Although Zitcha’s APIs are primarily designed for server-side implementation, some retailers choose to build client-side wrappers when a full backend integration is too complex or time-consuming.

To support these scenarios, Zitcha allows retailers to define which API endpoints require authentication. This flexibility means you can keep sensitive operations protected while allowing lightweight, browser-based tracking where needed.

For example:

• Authenticated endpoints: Secure critical data like product updates that should only be managed by backend systems.
• Unauthenticated endpoints: Keep event tracking such as ad clicks or page views open to send directly from the browser or mobile app.

Work with your Zitcha Solutions Architect to determine the most secure and efficient configuration for your integration.

When Not to Use Unauthenticated Integration

❌ Avoid unauthenticated integration for:

• Server-to-server data synchronisation
• Sending sensitive customer data or PII
• High-volume bulk data imports
• Scenarios requiring user-level access control

Our Recommendation

For production integrations handling sensitive data or high volumes, use our standard server-to-server authenticated API. It offers higher rate limits, stronger security, and full audit capabilities. See the Rate Limits section below. Contact the Zitcha team to discuss the best approach.

Getting Started

Prerequisites

Before you begin, you'll need:

Your API endpoint URL:

• Format: https://{your-organisation}.collect.au.zitcha.app
• Example: https://grocer.collect.au.zitcha.app
• Provided by the Zitcha team

Enabled endpoints:

• The Zitcha team configures which endpoints you can use without authentication
• Common endpoints: /v2/ad-impressions, /v2/ad-clicks, /v2/page-view

API documentation:

• See the Collect API reference

Requesting Unauthenticated Access

To enable unauthenticated access, contact the Zitcha team with:

Required information:

• Endpoints needed - Which API endpoints you want to access (e.g., /v2/ad-impressions, /v2/ad-clicks)
• Use case - Brief description of your integration (e.g., "Website ad tracking", "Mobile app analytics")
• Expected volume - Estimated requests per second and per day

Optional customisations:

• Custom rate limits - If you need higher limits than defaults (requires justification)
• Multiple endpoints - You can request access to multiple endpoints simultaneously

The Zitcha team will review your request and configure access.

Rate Limits

Unauthenticated endpoints have rate limits to ensure fair use and prevent abuse.

Note: Rate limits may change. See the table below for current limits.

Default Rate Limits

What Happens When You Exceed Limits?

If you exceed the rate limit, you'll get an HTTP 429 Too Many Requests response.

Need Higher Limits?

If your use case requires higher rate limits:

• Contact the Zitcha team
• Consider upgrading to authenticated server-to-server integration

Custom rate limits can be configured.

API Endpoints

For complete endpoint specifications, required fields, example payloads, and detailed documentation, see the Collect API reference.

Endpoint Categories

Analytics Endpoints - Track user behaviour and advertising performance

• Ad impressions, clicks, conversions
• Page views and video ad events

Data Endpoints - Update product catalogues and inventory data

• Product updates and stock counts
• Retail location updates and purchases

Common Issues & Solutions

Issue: "422 Validation Error"

Cause: Your request data doesn't match the required schema.

Solution:

• Review the Collect API reference
• Include all required fields
• Verify data types (strings, numbers, arrays)

Issue: "429 Rate Limit Exceeded"

Cause: You're sending too many requests too quickly.

Solution:

• Implement exponential backoff retry logic
• Review your request volume against rate limits
• Contact the Zitcha team for higher limits if needed

Issue: "403 Forbidden"

Cause: The endpoint isn't configured for unauthenticated access.

Solution:

• Verify the endpoint is in your approved list
• Contact the Zitcha team to enable additional endpoints
• Check you're using the correct API URL

Issue: High Error Rates

Causes:

• Invalid request payloads
• Missing required fields
• Incorrect data types

Solution:

• Review the Collect API reference for payload schemas
• Validate your requests against examples
• Check server logs for specific error messages

Frequently Asked Questions

Can I switch between authenticated and unauthenticated later?

Yes! You can change your integration method anytime. Contact the Zitcha team to discuss migration.

What's the difference in rate limits?

Refer to the Rate Limits table above for current limits.

Is unauthenticated access secure?

Yes, with limitations:

• Rate limiting prevents abuse
• Schema validation ensures data quality
• Not suitable for sensitive data

For maximum security, use authenticated server-to-server integration.

Can I use both methods?

Absolutely! Common patterns:

• Unauthenticated for browser-based tracking (page views, ad events)
• Authenticated for server-side data sync (product catalogues, purchases)

How do I get higher rate limits?

Contact the Zitcha team with your use case and expected volume.

Additional Resources

Documentation

• Collect API Reference - Complete endpoint specifications and schemas
• API Environments - Regional endpoints and authentication details
• What is the Zitcha Collect API? - Overview and use cases

Getting Help

For technical questions:

1. Review the Collect API reference
2. Check this guide for common issues
3. Review error messages and response codes
4. Contact the Zitcha team for further assistance