diff --git a/src/ConvertKit_API_Traits.php b/src/ConvertKit_API_Traits.php index b5fc993..396dcd4 100644 --- a/src/ConvertKit_API_Traits.php +++ b/src/ConvertKit_API_Traits.php @@ -227,16 +227,25 @@ public function get_landing_pages( * * @param integer $form_id Form ID. * @param string $email_address Email Address. + * @param string $referrer Referrer. * * @see https://developers.convertkit.com/v4.html#add-subscriber-to-form-by-email-address * * @return false|mixed */ - public function add_subscriber_to_form_by_email(int $form_id, string $email_address) + public function add_subscriber_to_form_by_email(int $form_id, string $email_address, string $referrer = '') { + // Build parameters. + $options = ['email_address' => $email_address]; + + if (!empty($referrer)) { + $options['referrer'] = $referrer; + } + + // Send request. return $this->post( sprintf('forms/%s/subscribers', $form_id), - ['email_address' => $email_address] + $options ); } @@ -245,6 +254,7 @@ public function add_subscriber_to_form_by_email(int $form_id, string $email_addr * * @param integer $form_id Form ID. * @param integer $subscriber_id Subscriber ID. + * @param string $referrer Referrer URL. * * @see https://developers.convertkit.com/v4.html#add-subscriber-to-form * @@ -252,9 +262,20 @@ public function add_subscriber_to_form_by_email(int $form_id, string $email_addr * * @return false|mixed */ - public function add_subscriber_to_form(int $form_id, int $subscriber_id) + public function add_subscriber_to_form(int $form_id, int $subscriber_id, string $referrer = '') { - return $this->post(sprintf('forms/%s/subscribers/%s', $form_id, $subscriber_id)); + // Build parameters. + $options = []; + + if (!empty($referrer)) { + $options['referrer'] = $referrer; + } + + // Send request. + return $this->post( + sprintf('forms/%s/subscribers/%s', $form_id, $subscriber_id), + $options + ); } /** diff --git a/tests/ConvertKitAPITest.php b/tests/ConvertKitAPITest.php index 9152123..3ba4191 100644 --- a/tests/ConvertKitAPITest.php +++ b/tests/ConvertKitAPITest.php @@ -95,6 +95,9 @@ protected function setUp(): void clientSecret: $_ENV['CONVERTKIT_OAUTH_CLIENT_SECRET'], accessToken: $_ENV['CONVERTKIT_OAUTH_ACCESS_TOKEN'] ); + + // Wait a second to avoid hitting a 429 rate limit. + sleep(1); } /** @@ -2731,6 +2734,118 @@ public function testAddSubscriberToFormByEmail() ); } + /** + * Test that add_subscriber_to_form_by_email() returns the expected data + * when a referrer is specified. + * + * @since 2.1.0 + * + * @return void + */ + public function testAddSubscriberToFormByEmailWithReferrer() + { + // Create subscriber. + $emailAddress = $this->generateEmailAddress(); + $subscriber = $this->api->create_subscriber( + email_address: $emailAddress, + ); + + // Set subscriber_id to ensure subscriber is unsubscribed after test. + $this->subscriber_ids[] = $subscriber->subscriber->id; + + // Add subscriber to form. + $result = $this->api->add_subscriber_to_form_by_email( + form_id: (int) $_ENV['CONVERTKIT_API_FORM_ID'], + email_address: $emailAddress, + referrer: 'https://mywebsite.com/bfpromo/', + ); + + $this->assertInstanceOf('stdClass', $result); + $this->assertArrayHasKey('subscriber', get_object_vars($result)); + $this->assertArrayHasKey('id', get_object_vars($result->subscriber)); + $this->assertEquals( + get_object_vars($result->subscriber)['email_address'], + $emailAddress + ); + + // Assert referrer data set for form subscriber. + $this->assertEquals( + $result->subscriber->referrer, + 'https://mywebsite.com/bfpromo/' + ); + } + + /** + * Test that add_subscriber_to_form_by_email() returns the expected data + * when a referrer is specified that includes UTM parameters. + * + * @since 2.1.0 + * + * @return void + */ + public function testAddSubscriberToFormByEmailWithReferrerUTMParams() + { + // Define referrer. + $referrerUTMParams = [ + 'utm_source' => 'facebook', + 'utm_medium' => 'cpc', + 'utm_campaign' => 'black_friday', + 'utm_term' => 'car_owners', + 'utm_content' => 'get_10_off', + ]; + $referrer = 'https://mywebsite.com/bfpromo/?' . http_build_query($referrerUTMParams); + + // Create subscriber. + $emailAddress = $this->generateEmailAddress(); + $subscriber = $this->api->create_subscriber( + email_address: $emailAddress, + ); + + // Set subscriber_id to ensure subscriber is unsubscribed after test. + $this->subscriber_ids[] = $subscriber->subscriber->id; + + // Add subscriber to form. + $result = $this->api->add_subscriber_to_form_by_email( + form_id: (int) $_ENV['CONVERTKIT_API_FORM_ID'], + email_address: $emailAddress, + referrer: $referrer, + ); + + $this->assertInstanceOf('stdClass', $result); + $this->assertArrayHasKey('subscriber', get_object_vars($result)); + $this->assertArrayHasKey('id', get_object_vars($result->subscriber)); + $this->assertEquals( + get_object_vars($result->subscriber)['email_address'], + $emailAddress + ); + + // Assert referrer data set for form subscriber. + $this->assertEquals( + $result->subscriber->referrer, + $referrer + ); + $this->assertEquals( + $result->subscriber->referrer_utm_parameters->source, + $referrerUTMParams['utm_source'] + ); + $this->assertEquals( + $result->subscriber->referrer_utm_parameters->medium, + $referrerUTMParams['utm_medium'] + ); + $this->assertEquals( + $result->subscriber->referrer_utm_parameters->campaign, + $referrerUTMParams['utm_campaign'] + ); + $this->assertEquals( + $result->subscriber->referrer_utm_parameters->term, + $referrerUTMParams['utm_term'] + ); + $this->assertEquals( + $result->subscriber->referrer_utm_parameters->content, + $referrerUTMParams['utm_content'] + ); + } + /** * Test that add_subscriber_to_form_by_email() throws a ClientException when an invalid * form ID is specified. @@ -2792,6 +2907,110 @@ public function testAddSubscriberToForm() $this->assertEquals(get_object_vars($result->subscriber)['id'], $subscriber->subscriber->id); } + /** + * Test that add_subscriber_to_form() returns the expected data + * when a referrer is specified. + * + * @since 2.1.0 + * + * @return void + */ + public function testAddSubscriberToFormWithReferrer() + { + // Create subscriber. + $subscriber = $this->api->create_subscriber( + email_address: $this->generateEmailAddress() + ); + + // Set subscriber_id to ensure subscriber is unsubscribed after test. + $this->subscriber_ids[] = $subscriber->subscriber->id; + + // Add subscriber to form. + $result = $this->api->add_subscriber_to_form( + form_id: (int) $_ENV['CONVERTKIT_API_FORM_ID'], + subscriber_id: $subscriber->subscriber->id, + referrer: 'https://mywebsite.com/bfpromo/', + ); + + $this->assertInstanceOf('stdClass', $result); + $this->assertArrayHasKey('subscriber', get_object_vars($result)); + $this->assertArrayHasKey('id', get_object_vars($result->subscriber)); + $this->assertEquals(get_object_vars($result->subscriber)['id'], $subscriber->subscriber->id); + + // Assert referrer data set for form subscriber. + $this->assertEquals( + $result->subscriber->referrer, + 'https://mywebsite.com/bfpromo/' + ); + } + + /** + * Test that add_subscriber_to_form() returns the expected data + * when a referrer is specified that includes UTM parameters. + * + * @since 2.1.0 + * + * @return void + */ + public function testAddSubscriberToFormWithReferrerUTMParams() + { + // Define referrer. + $referrerUTMParams = [ + 'utm_source' => 'facebook', + 'utm_medium' => 'cpc', + 'utm_campaign' => 'black_friday', + 'utm_term' => 'car_owners', + 'utm_content' => 'get_10_off', + ]; + $referrer = 'https://mywebsite.com/bfpromo/?' . http_build_query($referrerUTMParams); + + // Create subscriber. + $subscriber = $this->api->create_subscriber( + email_address: $this->generateEmailAddress() + ); + + // Set subscriber_id to ensure subscriber is unsubscribed after test. + $this->subscriber_ids[] = $subscriber->subscriber->id; + + // Add subscriber to form. + $result = $this->api->add_subscriber_to_form( + form_id: (int) $_ENV['CONVERTKIT_API_FORM_ID'], + subscriber_id: $subscriber->subscriber->id, + referrer: $referrer, + ); + + $this->assertInstanceOf('stdClass', $result); + $this->assertArrayHasKey('subscriber', get_object_vars($result)); + $this->assertArrayHasKey('id', get_object_vars($result->subscriber)); + $this->assertEquals(get_object_vars($result->subscriber)['id'], $subscriber->subscriber->id); + + // Assert referrer data set for form subscriber. + $this->assertEquals( + $result->subscriber->referrer, + $referrer + ); + $this->assertEquals( + $result->subscriber->referrer_utm_parameters->source, + $referrerUTMParams['utm_source'] + ); + $this->assertEquals( + $result->subscriber->referrer_utm_parameters->medium, + $referrerUTMParams['utm_medium'] + ); + $this->assertEquals( + $result->subscriber->referrer_utm_parameters->campaign, + $referrerUTMParams['utm_campaign'] + ); + $this->assertEquals( + $result->subscriber->referrer_utm_parameters->term, + $referrerUTMParams['utm_term'] + ); + $this->assertEquals( + $result->subscriber->referrer_utm_parameters->content, + $referrerUTMParams['utm_content'] + ); + } + /** * Test that add_subscriber_to_form() throws a ClientException when an invalid * form ID is specified. @@ -5086,11 +5305,11 @@ private function callPrivateMethod($obj, $name, array $args) * * @since 1.0.0 * - * @param string $domain Domain (default: convertkit.com). + * @param string $domain Domain (default: kit.com). * * @return string */ - private function generateEmailAddress($domain = 'convertkit.com') + private function generateEmailAddress($domain = 'kit.com') { return 'php-sdk-' . date('Y-m-d-H-i-s') . '-php-' . PHP_VERSION_ID . '@' . $domain; }