Posting Events via the Tagely API
Photo by Douglas Lopes on Unsplash
Tagely supports recording events programmatically via the Tagely API and provides an event tracking endpoint to do so. Examples of when you might want to do this are to record events such as subscription updates using the subscribeNoConv event. Often these are not associated with a corresponding page view and happen independently of direct user action on your website, such as when a subscription updates to a paid monthly charge after a free trial period.
The Tagely API also makes it possible to record events without installation of the Tagely pixel base code if you wish to do so for any reason. Your server can also post tracking data (UTM parameters, affiliate IDs and sub IDs) directly through the API to associate with each event.
Overview
The Event Tracking API endpoint is designed for clients to track various user events such as purchases or subscriptions. It accepts data through a POST request and records the event details in the database, provided the request is authenticated with a valid user ID and API key.
Endpoint
The event tracking endpoint is: https://tagely.com/t/track_api
Authentication
Each request must include a valid user ID and API key for authentication. Unauthorized or incomplete requests will not be processed.
Request Format
The request must be a POST request with the following parameters:
- user_id (required): The user’s unique identifier.
- api_key (required): The API key associated with the user.
- type (required): The type of event. Valid types are “event”, “purchase”, “subscribe”, “subscribeNoConv”.
- args (required): A JSON string containing additional event details. Example format: {“campaign_id”:88,”unique_id”:123,”order_total”:525.50,”vanity_code”:”jeff”,”desks”:3,”chairs”:5}.
- tgly_aid: Additional affiliate ID parameter (optional).
- utm_source, utm_medium, utm_campaign, utm_term, utm_content: UTM parameters for tracking (optional).
- tgly_subid1, tgly_subid2, tgly_subid3: Affiliate Sub-ID parameters (optional).
Response Format
The response will be in JSON format with the following structure:
- status: Indicates the success or failure of the request (“success” or “error”).
- message: Descriptive message about the result.
- event_id (optional): The unique identifier of the recorded event, included in successful responses.
Response Status Codes
- 200 OK: The request was successful, and the event was recorded.
- 400 Bad Request: Required fields are missing, or input validation failed.
- 401 Unauthorized: Invalid user ID or API key.
- 403 Forbidden: Account disabled, subscription inactive, or account setup incomplete.
- 405 Method Not Allowed: Incorrect request method (only POST is allowed).
Usage Example
-d ‘user_id=5’ \
-d ‘api_key=<API_KEY>’ \
-d ‘type=purchase’ \
-d ‘args={“campaign_id”:”88″,”unique_id”:”123″,”order_total”:”525.50″,”vanity_code”:”codici”,”desks”:”1″,”chairs”:”2″}’
Notes
– Ensure that the API is called over HTTPS to protect sensitive information.
– The JSON format in the args parameter must be valid; otherwise, the request will be rejected.
– This endpoint is intended for server-to-server communication. Keep the API key confidential.
Error Handling
In case of an error, the response will include a descriptive message to help diagnose the issue. Ensure that your client application handles these errors gracefully.
