Skip to content

Commit 38cb077

Browse files
n7studiosn7studios
authored
Merge pull request #97 from Kit/add-form-referrer-support
Form Subscribe: Add `referrer` support
2 parents d19ec8d + 907907b commit 38cb077

File tree

2 files changed

+246
-6
lines changed

2 files changed

+246
-6
lines changed

‎src/ConvertKit_API_Traits.php‎

Lines changed: 25 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -227,16 +227,25 @@ public function get_landing_pages(
227227
*
228228
* @param integer $form_id Form ID.
229229
* @param string $email_address Email Address.
230+
* @param string $referrer Referrer.
230231
*
231232
* @see https://developers.convertkit.com/v4.html#add-subscriber-to-form-by-email-address
232233
*
233234
* @return false|mixed
234235
*/
235-
public function add_subscriber_to_form_by_email(int $form_id, string $email_address)
236+
public function add_subscriber_to_form_by_email(int $form_id, string $email_address, string $referrer = '')
236237
{
238+
// Build parameters.
239+
$options = ['email_address' => $email_address];
240+
241+
if (!empty($referrer)) {
242+
$options['referrer'] = $referrer;
243+
}
244+
245+
// Send request.
237246
return $this->post(
238247
sprintf('forms/%s/subscribers', $form_id),
239-
['email_address' => $email_address]
248+
$options
240249
);
241250
}
242251

@@ -245,16 +254,28 @@ public function add_subscriber_to_form_by_email(int $form_id, string $email_addr
245254
*
246255
* @param integer $form_id Form ID.
247256
* @param integer $subscriber_id Subscriber ID.
257+
* @param string $referrer Referrer URL.
248258
*
249259
* @see https://developers.convertkit.com/v4.html#add-subscriber-to-form
250260
*
251261
* @since 2.0.0
252262
*
253263
* @return false|mixed
254264
*/
255-
public function add_subscriber_to_form(int $form_id, int $subscriber_id)
265+
public function add_subscriber_to_form(int $form_id, int $subscriber_id, string $referrer = '')
256266
{
257-
return $this->post(sprintf('forms/%s/subscribers/%s', $form_id, $subscriber_id));
267+
// Build parameters.
268+
$options = [];
269+
270+
if (!empty($referrer)) {
271+
$options['referrer'] = $referrer;
272+
}
273+
274+
// Send request.
275+
return $this->post(
276+
sprintf('forms/%s/subscribers/%s', $form_id, $subscriber_id),
277+
$options
278+
);
258279
}
259280

260281
/**

‎tests/ConvertKitAPITest.php‎

Lines changed: 221 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -95,6 +95,9 @@ protected function setUp(): void
9595
clientSecret: $_ENV['CONVERTKIT_OAUTH_CLIENT_SECRET'],
9696
accessToken: $_ENV['CONVERTKIT_OAUTH_ACCESS_TOKEN']
9797
);
98+
99+
// Wait a second to avoid hitting a 429 rate limit.
100+
sleep(1);
98101
}
99102

100103
/**
@@ -2731,6 +2734,118 @@ public function testAddSubscriberToFormByEmail()
27312734
);
27322735
}
27332736

2737+
/**
2738+
* Test that add_subscriber_to_form_by_email() returns the expected data
2739+
* when a referrer is specified.
2740+
*
2741+
* @since 2.1.0
2742+
*
2743+
* @return void
2744+
*/
2745+
public function testAddSubscriberToFormByEmailWithReferrer()
2746+
{
2747+
// Create subscriber.
2748+
$emailAddress = $this->generateEmailAddress();
2749+
$subscriber = $this->api->create_subscriber(
2750+
email_address: $emailAddress,
2751+
);
2752+
2753+
// Set subscriber_id to ensure subscriber is unsubscribed after test.
2754+
$this->subscriber_ids[] = $subscriber->subscriber->id;
2755+
2756+
// Add subscriber to form.
2757+
$result = $this->api->add_subscriber_to_form_by_email(
2758+
form_id: (int) $_ENV['CONVERTKIT_API_FORM_ID'],
2759+
email_address: $emailAddress,
2760+
referrer: 'https://mywebsite.com/bfpromo/',
2761+
);
2762+
2763+
$this->assertInstanceOf('stdClass', $result);
2764+
$this->assertArrayHasKey('subscriber', get_object_vars($result));
2765+
$this->assertArrayHasKey('id', get_object_vars($result->subscriber));
2766+
$this->assertEquals(
2767+
get_object_vars($result->subscriber)['email_address'],
2768+
$emailAddress
2769+
);
2770+
2771+
// Assert referrer data set for form subscriber.
2772+
$this->assertEquals(
2773+
$result->subscriber->referrer,
2774+
'https://mywebsite.com/bfpromo/'
2775+
);
2776+
}
2777+
2778+
/**
2779+
* Test that add_subscriber_to_form_by_email() returns the expected data
2780+
* when a referrer is specified that includes UTM parameters.
2781+
*
2782+
* @since 2.1.0
2783+
*
2784+
* @return void
2785+
*/
2786+
public function testAddSubscriberToFormByEmailWithReferrerUTMParams()
2787+
{
2788+
// Define referrer.
2789+
$referrerUTMParams = [
2790+
'utm_source' => 'facebook',
2791+
'utm_medium' => 'cpc',
2792+
'utm_campaign' => 'black_friday',
2793+
'utm_term' => 'car_owners',
2794+
'utm_content' => 'get_10_off',
2795+
];
2796+
$referrer = 'https://mywebsite.com/bfpromo/?' . http_build_query($referrerUTMParams);
2797+
2798+
// Create subscriber.
2799+
$emailAddress = $this->generateEmailAddress();
2800+
$subscriber = $this->api->create_subscriber(
2801+
email_address: $emailAddress,
2802+
);
2803+
2804+
// Set subscriber_id to ensure subscriber is unsubscribed after test.
2805+
$this->subscriber_ids[] = $subscriber->subscriber->id;
2806+
2807+
// Add subscriber to form.
2808+
$result = $this->api->add_subscriber_to_form_by_email(
2809+
form_id: (int) $_ENV['CONVERTKIT_API_FORM_ID'],
2810+
email_address: $emailAddress,
2811+
referrer: $referrer,
2812+
);
2813+
2814+
$this->assertInstanceOf('stdClass', $result);
2815+
$this->assertArrayHasKey('subscriber', get_object_vars($result));
2816+
$this->assertArrayHasKey('id', get_object_vars($result->subscriber));
2817+
$this->assertEquals(
2818+
get_object_vars($result->subscriber)['email_address'],
2819+
$emailAddress
2820+
);
2821+
2822+
// Assert referrer data set for form subscriber.
2823+
$this->assertEquals(
2824+
$result->subscriber->referrer,
2825+
$referrer
2826+
);
2827+
$this->assertEquals(
2828+
$result->subscriber->referrer_utm_parameters->source,
2829+
$referrerUTMParams['utm_source']
2830+
);
2831+
$this->assertEquals(
2832+
$result->subscriber->referrer_utm_parameters->medium,
2833+
$referrerUTMParams['utm_medium']
2834+
);
2835+
$this->assertEquals(
2836+
$result->subscriber->referrer_utm_parameters->campaign,
2837+
$referrerUTMParams['utm_campaign']
2838+
);
2839+
$this->assertEquals(
2840+
$result->subscriber->referrer_utm_parameters->term,
2841+
$referrerUTMParams['utm_term']
2842+
);
2843+
$this->assertEquals(
2844+
$result->subscriber->referrer_utm_parameters->content,
2845+
$referrerUTMParams['utm_content']
2846+
);
2847+
}
2848+
27342849
/**
27352850
* Test that add_subscriber_to_form_by_email() throws a ClientException when an invalid
27362851
* form ID is specified.
@@ -2792,6 +2907,110 @@ public function testAddSubscriberToForm()
27922907
$this->assertEquals(get_object_vars($result->subscriber)['id'], $subscriber->subscriber->id);
27932908
}
27942909

2910+
/**
2911+
* Test that add_subscriber_to_form() returns the expected data
2912+
* when a referrer is specified.
2913+
*
2914+
* @since 2.1.0
2915+
*
2916+
* @return void
2917+
*/
2918+
public function testAddSubscriberToFormWithReferrer()
2919+
{
2920+
// Create subscriber.
2921+
$subscriber = $this->api->create_subscriber(
2922+
email_address: $this->generateEmailAddress()
2923+
);
2924+
2925+
// Set subscriber_id to ensure subscriber is unsubscribed after test.
2926+
$this->subscriber_ids[] = $subscriber->subscriber->id;
2927+
2928+
// Add subscriber to form.
2929+
$result = $this->api->add_subscriber_to_form(
2930+
form_id: (int) $_ENV['CONVERTKIT_API_FORM_ID'],
2931+
subscriber_id: $subscriber->subscriber->id,
2932+
referrer: 'https://mywebsite.com/bfpromo/',
2933+
);
2934+
2935+
$this->assertInstanceOf('stdClass', $result);
2936+
$this->assertArrayHasKey('subscriber', get_object_vars($result));
2937+
$this->assertArrayHasKey('id', get_object_vars($result->subscriber));
2938+
$this->assertEquals(get_object_vars($result->subscriber)['id'], $subscriber->subscriber->id);
2939+
2940+
// Assert referrer data set for form subscriber.
2941+
$this->assertEquals(
2942+
$result->subscriber->referrer,
2943+
'https://mywebsite.com/bfpromo/'
2944+
);
2945+
}
2946+
2947+
/**
2948+
* Test that add_subscriber_to_form() returns the expected data
2949+
* when a referrer is specified that includes UTM parameters.
2950+
*
2951+
* @since 2.1.0
2952+
*
2953+
* @return void
2954+
*/
2955+
public function testAddSubscriberToFormWithReferrerUTMParams()
2956+
{
2957+
// Define referrer.
2958+
$referrerUTMParams = [
2959+
'utm_source' => 'facebook',
2960+
'utm_medium' => 'cpc',
2961+
'utm_campaign' => 'black_friday',
2962+
'utm_term' => 'car_owners',
2963+
'utm_content' => 'get_10_off',
2964+
];
2965+
$referrer = 'https://mywebsite.com/bfpromo/?' . http_build_query($referrerUTMParams);
2966+
2967+
// Create subscriber.
2968+
$subscriber = $this->api->create_subscriber(
2969+
email_address: $this->generateEmailAddress()
2970+
);
2971+
2972+
// Set subscriber_id to ensure subscriber is unsubscribed after test.
2973+
$this->subscriber_ids[] = $subscriber->subscriber->id;
2974+
2975+
// Add subscriber to form.
2976+
$result = $this->api->add_subscriber_to_form(
2977+
form_id: (int) $_ENV['CONVERTKIT_API_FORM_ID'],
2978+
subscriber_id: $subscriber->subscriber->id,
2979+
referrer: $referrer,
2980+
);
2981+
2982+
$this->assertInstanceOf('stdClass', $result);
2983+
$this->assertArrayHasKey('subscriber', get_object_vars($result));
2984+
$this->assertArrayHasKey('id', get_object_vars($result->subscriber));
2985+
$this->assertEquals(get_object_vars($result->subscriber)['id'], $subscriber->subscriber->id);
2986+
2987+
// Assert referrer data set for form subscriber.
2988+
$this->assertEquals(
2989+
$result->subscriber->referrer,
2990+
$referrer
2991+
);
2992+
$this->assertEquals(
2993+
$result->subscriber->referrer_utm_parameters->source,
2994+
$referrerUTMParams['utm_source']
2995+
);
2996+
$this->assertEquals(
2997+
$result->subscriber->referrer_utm_parameters->medium,
2998+
$referrerUTMParams['utm_medium']
2999+
);
3000+
$this->assertEquals(
3001+
$result->subscriber->referrer_utm_parameters->campaign,
3002+
$referrerUTMParams['utm_campaign']
3003+
);
3004+
$this->assertEquals(
3005+
$result->subscriber->referrer_utm_parameters->term,
3006+
$referrerUTMParams['utm_term']
3007+
);
3008+
$this->assertEquals(
3009+
$result->subscriber->referrer_utm_parameters->content,
3010+
$referrerUTMParams['utm_content']
3011+
);
3012+
}
3013+
27953014
/**
27963015
* Test that add_subscriber_to_form() throws a ClientException when an invalid
27973016
* form ID is specified.
@@ -5086,11 +5305,11 @@ private function callPrivateMethod($obj, $name, array $args)
50865305
*
50875306
* @since 1.0.0
50885307
*
5089-
* @param string $domain Domain (default: convertkit.com).
5308+
* @param string $domain Domain (default: kit.com).
50905309
*
50915310
* @return string
50925311
*/
5093-
private function generateEmailAddress($domain = 'convertkit.com')
5312+
private function generateEmailAddress($domain = 'kit.com')
50945313
{
50955314
return 'php-sdk-' . date('Y-m-d-H-i-s') . '-php-' . PHP_VERSION_ID . '@' . $domain;
50965315
}

0 commit comments

Comments
 (0)