Download the PHP package viezel/amplitude-php-sdk without Composer

Amplitude PHP SDK

Table of Contents

1. About the Project
2. Project Status
3. Getting Started
4. Anonymous users
5. User properties
   1. Adding user properties on event object
   2. Use-Case: Events for Many Users
6. Events
   1. Just send it!
   2. Using Event object
      1. Setting event properties
      2. Unsetting event properties
      3. Sending or Queuing the Event
7. Tips and tricks
   1. Use Amplitude efficiently
   2. Don't forget the eventType
   3. Custom Event Factory
   4. queueEvent() vs logEvent()

About the Project

This is a moderately thin PHP API for Amplitude, forked from zumba/Amplitude-php and adapted.

• Multiple Events using Same User & Amplitude App - When you are tracking possibly multiple events, all for the same user, all for the same Amplitude app. This library provides a Singleton instance that allows initializing the API key and user info once for the page load, that gets used for any events logged during that page load.
• Multiple Events across Multiple Users and possibly multiple Amplitude Apps - For times you may need to log multiple events for a lot of different users, possibly using different amplitude apps.

Getting Started

You can now use the sdk like below:

When you are initially getting your application set up, if you do not see your event show up in Amplitude, you may need to do a little troubleshooting. Normally your indication that "it worked" is when you see your event show up in your Amplitude app for the first time.

If you never see that first event show up, you can see what Amplitude's response is when the event is logged. This may help find and fix the problem (such as an invalid API key, PHP environment errors, connection problems, etc.)

Amplitude uses Psr\Logger for logging the communication with the Amplitude HTTP API. You can take advantage of this by setting a logger (using $amlitude->setLogger()) to help catch any problems.

Anonymous Users

Since this is a PHP SDK, there are a lot of options for tracking Anonymous users. Since this could be run in CLI mode or as a cron job, this SDK does not handle sessions for you.

Your application will need to figure out a way to track users across multiple page loads, chances are your app is already doing this with PHP sessions or something like it.

Once you have that unique identifier that allows an anonymous user to be tracked between page loads, set that as the deviceId. Do this for both logged-in users and anonymous users, that way once a user is logged-in, their past events will be linked to the user.

User Properties

There is one main way to set user properties, and this will send the user properties with the next Amplitude event sent to Amplitude:

You would typically call this right before calling logQueuedEvents() to make sure it gets sent with the first queued event (if there are any events).

Using this method, it only sends the user information with one event, since once a user property is set in Amplitude it persists for all events that match the user ID or event ID.

Also note that if there happens to be no events sent after setUserProperties() are sent, those properties will not get sent to Amplitude.

One option, is to use a login event that adds the user info when the user has logged in, and sends it in a login event. That way you only send user properties for the page load that the user logs in.

Alternatively, just add the user properties with every page load when initializing the Amplitude object. This is the option used in the examples.

Adding User Properties on Event Object

Another option for setting the user properties, is setting them on the Event object itself. You can do this by setting/changing userProperties, or by using the setUserProperties() method on the Event object.

You would typically use this in situations similar to the one in the next section, for times you may be sending events for different users in the same page load.

You can find more information about how the Event object works below in the Events section.

Use-Case: Events for Many Users

In situations where you will be sending many Amplitude events for different users, you can actually add the user properties on the event object itself as we covered in the previous section. In fact, everything can be set on the event object itself except for the API Key.

For example:

See the next section for more details about what you can do with the Event object.

Events

This library is very flexible, in terms of giving you options for how to set up the event to be sent to Amplitude. Use the method that best suites your own preferences and project needs.

Just Send It!

The first option is the easiest, the one used in the main example. Just call either queueEvent or logEvent with the event type and event properties if there are any. But know that depending on which you use, you will have to call the appropriate method to send your events.

• queueEvent queues an event that will be sent along with all queued event by logQueuedEvents.
• logEvent sends the event right away.

Using Event Object

You have the option to use an event object to set up the event, if this is more convenient for your use case. The example of how to do this is below:

Setting event properties

As far as setting the event properties on the event object, you have a few options once you have that $event object:

For times that you just want to quickly set some properties on the next event that will be queued or sent, but aren't ready to actually send or queue the event yet, you can pass in an array of properties into the $amplitude->event() method.

Unsetting event properties

If a property has already been set on an event, you can unset it.

Sending or Queuing the Event

Once you have set all the event properties, you can then send or queue the event, just by calling $amplitude->queueEvent() or $amplitude->logEvent().

Note: If you just created a new Event object, before calling queueEvent() or logEvent(), you must pass that event into amplitude like this:

If however, you used the event method to get the event, no need to pass it back into Amplitude.

In other words, when dealing with the Event object directly, it must have passed through Amplitude's event() method one way or the other before attempting to call queueEvent() or logEvent().

Tips and tricks

Use Amplitude efficiently

If you need to set up an event across different parts of the code, you could pass that event around, but you don't have to, as Amplitude keeps track of the next event object to be sent or queued as long as you're working with the same instance. So you could do something like this:

Don't forget the eventType

When using the event object, remember that the eventType must be set one way or another before the event is queued or logged.

Note that setting it when calling queueEvent() or logEvent() will overwrite the eventType if it is already set in the event object, but any other properties set on the event will remain intact.

Custom Event Factory

Say you wanted to make some sort of factory that is cranking out events to send, maybe even each with it's own user ID already set... You could do something like this:

queueEvent() vs. logEvent()

The difference?

• Both:
  • Require the eventType to be set and non-empty.
• logEvent():
  • Requires API Key to be set, will throw exception if not set yet.
  • Requires either userId or deviceId to be set, will throw exception if not set either on the amplitude instance, or on the event itself.
  • Always sends the event at the time it is called, assuming requirements met.
• queueEvent():
  • Does not require API key to be set first.
  • Does not require userId or deviceId to be set first.
  • What ever happens, it will add the event to an internal queue. This queue does not persist across page loads, if any remain in the queue they are lost if not send during that page load.
  • If you do use this, immediately after initializing Amplitude (setting the API key and either the userId or deviceId in amplitude), be sure to call $amplitude->logQueuedEvents() to send any events that are on the queue. If nothing is on the queue, no worries, nothing happens.

Why would you ever use logEvent() instead of queueEvent()? The use case for that is when sending events for multiple users, in such a way that you are initializing the data then sending right away. Using logEvent() in that case you would catch right away if something is not initialized right away (it will throw a logic exception), instead of "quietly" starting up a queue that you may never deal with if not expecting there to be one.

TL;DR: If you know that you will always be initializing amplitude before calling an event, you can use logEvent() directly. Otherwise use queueEvent() and just be sure to call $amplitude->logQueuedEvents() once you do have Amplitude initialized and user data set.

Troubleshooting

Stand-alone Script

Below is a stand-alone script, meant to be copied into a PHP file at the root of your application's document root. Just change the APIKEY and if needed, adjust the line that requires the autoload.php file for composer. Then visit the script's URL from a browser to see any messages logged.

Troubleshooting Tips

• The Amplitude library will throw a \DomainException. For instance
  • if you try to queue an event with an empty event_type the library will throw a \DomainException
• Make sure PHP error logging is enabled (or display errors is enabled), so you can see any PHP errors that may point to the problem.
• Use the setLogger(...) method in amplitude to use your app's logging or your own custom logger like the standalone test script above. As long as it implements the Psr\Log\LoggerInterface.
  • If no logs are generated: It did not attempt to send an event after the point your app's logger was set, or the event was logged using a different instance that does not have a logger set.
  • If you see Curl error: logged: then something went wrong when it tried to send the request, the error message and context should help point to the problem.
  • If there are no curl errors, it will log a message starting with Amplitude HTTP API response::
    • success with httpCode = 200 : Amplitude got the request and the event should have been logged. If you are not seeing it in Amplitude, check again after a few minutes, sometimes Amplitude can lag a little behind.
    • Anything Else: The event was not logged successfully, refer to the message and context to help troubleshoot the problem.