Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Form Subscribe: Add referrer support #97

Merged
merged 19 commits into from
Dec 6, 2024
Merged

Form Subscribe: Add referrer support #97

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
9f60dc7
Add `referrer` parameter to `add_subscriber_to_form` and `add_subscri…
n7studios Dec 4, 2024
dcb923e
Improve tests
n7studios Dec 4, 2024
a28254a
Don’t remove subscribers after test
n7studios Dec 4, 2024
a1de775
Debug test
n7studios Dec 4, 2024
26ea154
Remove test debugging
n7studios Dec 4, 2024
f904ac7
Debug tests, again
n7studios Dec 4, 2024
43b14ba
Delay tests
n7studios Dec 4, 2024
85b4988
Debug tests
n7studios Dec 4, 2024
eb494bd
Fix tests
n7studios Dec 4, 2024
0493a54
Add helper method to assert referrer set
n7studios Dec 4, 2024
f0ff1c6
Debug tests
n7studios Dec 4, 2024
1afc900
Debug tests
n7studios Dec 4, 2024
9653080
Revert debugging
n7studios Dec 4, 2024
513e73c
Add a pause between each test to avoid a 429 rate limit
n7studios Dec 4, 2024
5dd3d01
Check result of form subscribe instead of separate API query in tests
n7studios Dec 4, 2024
3a2c694
Merge remote-tracking branch 'origin/tests-run-phpstan' into add-form…
n7studios Dec 4, 2024
98895dc
Coding standards
n7studios Dec 4, 2024
710802c
Bump to 2.1.0 for next release
n7studios Dec 4, 2024
907907b
Merge remote-tracking branch 'origin/tests-run-phpstan' into add-form…
n7studios Dec 4, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 25 additions & 4 deletions src/ConvertKit_API_Traits.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
);
}

Expand All @@ -245,16 +254,28 @@ 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
*
* @since 2.0.0
*
* @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
);
}

/**
Expand Down
223 changes: 221 additions & 2 deletions tests/ConvertKitAPITest.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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);
}

/**
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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;
}
Expand Down
Loading