====== mailResume() ======
''void **mailResume**(string //PersonID//, int //Serienmail//, int //Zeitpunkt//, [string //C1//, string //C2//, string //C3//, string //C4//, string //C5//])''
Diese Funktion versendet im laufenden Interview eine E-Mail mit einem Link, um das Interview später fortzusetzen. Dies ist vor allem in Verbindung mit einer gezielten Unterbrechung in mehrwelligen Erhebungen sinnvoll (''[[:de:create:functions:buttonhide|buttonHide()]]'').
**Wichtig:** Der Versand funktioniert nur dann, wenn der Teilnehmer bereits in der Serienmail-Adressliste registriert ist.
* //PersonID//\\ Die Personenkennung des Adressaten, der die E-Mail erhalten soll. Falls das Interview durch eine Serienmail-Einladung begonnen wurde, können Sie ''false'' eintragen, die passende Kennung wird dann automatisch ermittelt. Alternativ kann die Personenkennung mittels ''[[:de:create:functions:caseserial|caseSerial()]]'' ermittelt werden.
* //Serienmail//\\ (Numerische) Kennung der Serienmail, die an den Teilnehmer verschickt werden soll. Im Karteireiter //Erinnerungen/Folgemail// der Serienmail muss für //Art der Folgemail// der Wert "Erinnerung oder Fortsetzung" eingestellt sein. Bitte beachten Sie die Hinweise unten.
* //Zeitpunkt//\\ Entweder die Verzögerung bis zum Versand (in Sekunden, maximal 153900000) __oder__ ein Unix-Zeitstempel, der den Zeitpunkt für den nächsten Versand definiert.
* //C1// bis //C5// (optional)\\ Wenn Sie hier einen Text angeben (optional), können Sie diesen Text mithilfe der Platzhalter ''%custom1%'' bis ''%custom5%'' in der Serienmail verwenden. In Verbindung mit ''value()'' können Sie beispielsweise Antworten aus dem laufenden Interview in der E-Mail anzeigen.
===== Hinweise =====
**Hinweis:** Eine Serienmail kann bei Verwendung von ''mailResume()'' mehrfach an denselben Adressaten verschickt werden.
**Hinweis:** Der Platzhalter ''%link%'' in der Serienmail wird nicht durch einen regulären personalisierten Link ersetzte (bei dessen Aufruf das Interview u.U. von Neuem startet), sondern durch einen Link direkt zum laufenden Interview.
**Hinweis:** Falls die E-Mail-Adressen der Teilnehmer nicht a-priori bekannt sind, müssen diese zu Beginn des ersten Fragebogens erhoben werden, damit man ''mailResume()'' einsetzen kann. Alternativ ist die Verwendung getrennter Fragebögen und der Funktion ''[[:de:create:functions:mailschedule|mailSchedule()]]'' möglich ([[:de:survey:opt-in-live|Mehrwellige Befragungen bei Selbstrekrutierung]]).
**Tipp:** Im Internet gibt es zahlreiche Websites, die ein Datum in einen Unix-Zeitstempel umrechnen können, z.B. [[http://www.unixtime.de/|unixtime.de]]. Auch die [[http://www.php.net/manual/de/ref.datetime.php|Datums- und Zeit-Funktionen]] von PHP (insbesondere ''[[http://php.net/manual/de/function.mktime.php|mktime()]]'' und ''[[http://www.php.net/manual/de/function.strtotime.php|strtotime()]]'') sind dafür geeignet.
**Tipp:** Wenn Sie den Versand der Einladung nicht zu einem bestimmten Zeitpunkt, sondern nach einer bestimmten Verzögerung wünschen, geben Sie die Verzögerung an. Denn ''mailResume()'' kann den doppelten Versand von Mails dann besser verhindern.
===== Unterbrechung eines Interviews =====
Im folgenden Beispiel wurde der Teilnehmer mittels Serienmail zum Fragebogen eingeladen. In der Mitte des Fragebogens wird eine Unterbrecher-Seite (''[[:de:create:functions:buttonhide|buttonHide()]]'') platziert und der Text "ende1" angezeigt. Nach der 24 Stunden erhält der Teilnehmer eine E-Mail, dass er nun den zweiten Teil des Frgebogens ausfüllen möge. Der Link in der E-Mail führt ihn zur nächsten Seite im vorher unterbrochenen Fragebogen.
**Wichtig:** Die Funktion ''caseTime()'' funktioniert nur dann korrekt, wenn Sie in den **Projekt-Einstellungen** im Karteireiter //Datenschutz// das Häkchen bei "Zeit und Verweildauer während der Befragung aufzeichnen" nicht entfernt haben. Die Verweildauer ist für die hier vorgeschlagenen Unterbrecherseiten eine erforderliche Information.
// Falls der Zurück-Knopf im Fragebogen eingeschaltet ist,
// sollte er auf dieser Seite nicht erscheinen
option('backbutton', false);
// Prüfen, wie viel Zeit seit Beginn des Befragung vergangen ist
// Falls es weniger als 24 Stunden sind (24 * 3600 Sekunden), wird das Interview unterbrochen
if (caseTime('begin') < 24 * 3600) {
text('ende1'); // Verabschiedung zum ersten Teil anzeigen
option('resume', true); // Hinweis auf fortgesetztes Interview verhindern
option('nextbutton', false); // Weiter-Knopf ausblenden (Interview unterbrechen)
// Serienmail mit der Kennung 3 morgen um dieselbe Zeit versenden (also in genau 24 Stunden)
mailResume(false, 3, 24 * 3600);
} else {
// Ist der Teilnehmer nach 24 Stunden zurückgekehrt? Dann geht es nun direkt weiter
goToPage('next');
}
Alternativ können Sie auch die Zeit überprüfen, die sei dem ersten Aufruf der Seite (und damit seit Vorbereitung der E-Mail) vergangen ist:
// Zurück-Knopf bei Bedarf abschalten
option('backbutton', false);
// Zeit des ersten Aufrufs speichern
// Wegen isset() und registerVariable() wird der Block nur beim ersten Mal ausgeführt
if (!isset($timeBreak1)) {
// Zeit speichern
$timeBreak1 = time();
registerVariable($timeBreak1);
// E-Mail vorbereiten
// Serienmail mit der Kennung 2 genau in 14 Tagen versenden
mailResume(false, 3, 14 * 24 * 3600);
}
// Prüfen, wie viel Zeit seit dem ersten Aufruf der Seite vergangen ist
// Unterbrechung, falls es weniger als 14 Tage sind (14 * 24 * 3600 Sekunden)
if (time() - $timeBreak1 < 14 * 24 * 3600) {
text('ende1'); // Verabschiedung zum ersten Teil anzeigen
option('nextbutton', false); // Weiter-Knopf ausblenden (Interview unterbrechen)
} else {
// Evtl. soll der Fortschrittsbalken angepasst werden?
option('progress', 0);
// Ist der Teilnehmer nach 14 Tagen zurückgekehrt? Dann geht es nun weiter
goToPage('next');
}
===== Infomail an den Projektleiter =====
Die Funktion ''mailResume()'' lässt sich auch dafür "missbrauchen", den Projektleiter über eingehende Interviews zu informieren. Dafür ist es notwendig, die E-Mail-Adresse des Projektleiters in die Adressliste zu importieren ([[:de:survey:mailing|Serienmail versenden]]). Wichtig dabei: Die Adresse darf nicht //anonym// importiert werden.
Aus der Adressliste kann anschließend die Personenkennung des Adresseintrags ermittelt werden. Diese wird angezeigt, wenn man mit der Maus über den Adresseintrag führt oder diesen zum Bearbeiten öffnet. Im Beispiel wird als Personenkennung "ABCDE123" angenommen.
Wurde zusätzlich noch eine Serienmail (Nummer 3) angelegt, informiert folgender PHP-Code, dass ein Teilnehmer die aktuelle Seite im Fragebogen erreicht hat.
mailResume('ABCDE123', 3, 0);
===== Serienmail nach Opt-In-Frage =====
Mit einer Frage vom Typ [[:de:create:questions:opt-in]] kann man im Fragebogen E-Mail-Adressen abfragen und direkt in die Adressliste (**Einladungen verschicken** -> **Adressliste**) eintragen, sodass man später Serienmails an die E-Mail-Adressen versenden kann.
Dieser Abschnitt erklärt, wie man mittels ''[[:de:create:functions:mailschedule]]'' automatisch den zeitgesteuerten oder unmittelbaren Versand einer Serienmail an die eingetragene E-Mail-Adresse auslöst.
Bei der Opt-In-Frage gibt es zwei Mechanismen: Das Double-Opt-In (der Teilnehmer muss den Adresseintrag erst via Bestätigungsmail bestätigen, empfohlen) und das Single-Opt-In, bei welchem die (möglicherweise falsche) E-Mail-Adresse direkt gespeichert wird.
- Beim Double-Opt-In ist es sinnvoll, den Versand erst nach Bestätigung der Mailadresse auszulösen. Wie das funktioniert wird in folgendem Kapitel erläutert: [[:/de:survey:opt-in-live]]
- Wenn die Serienmail direkt verschickt werden soll, kann man die Bestätigungsmail der (Double-)Opt-In-Frage zugleich als Einladungsmail zu einem Fragebogen genutzt werden (//Weitere Einstellungen// -> //Weiterleitung nach Bestätigung// -> //Fragebogen-Link aus//). Allerdings ist der Link in der Bestätigungsmail nur 24 Stunden gültig. Eine "richtige" Serienmail-Einladung ist i.d.R. für den gesamten Erhebungszeitraum gültig, sofern die Gültigkeit in den Serienmail-Einstellungen nicht begrenzt wird.
- Wenn eine "richtige" Serienmail im Anschluss an ein Single-Opt-In verschickt werden soll, kommt der Befehl ''mailSchedule()'' zum Einsatz. Dies wird nachfolgend genauer erläutert.
Der PHP-Code mit dem ''mailSchedule()'' wird (frühestens) auf der Seite platziert, welche auf die Opt-In-Frage folgt. Denn erst dort kennt der Befragungsserver die neue E-Mail-Adresse und hat ihr eine Personenkennung (SERIAL) zugewiesen. Diese Personenkennung ist als erster Parameter für die Funktion ''mailSchedule()'' erforderlich (so sonst häufig ''false'') verwendet wird. Woher bekommt man die Kennung? Wenn der Teilnehmer in der Opt-In-Frage eine E-Mail-Adresse eingetragen hat, dann ist sie im Datensatz in einer Variable vermerkt, welche dieselbe Kennung wie die Opt-In-Frage hat.
Im folgenden Beispiel hätte die Opt-In-Frage auf Seite 9 die Kennung "OI01". Auf Seite 10 (oder später) würde der folgende PHP-Code dann sofort die Serienmail mit der ID 2 versenden. Das ''value('OI01')'' liefert die Teilnehmerkennung (SERIAL) des neuen Adresseintrags.
mailSchedule(value('OI01'), 2, 0);
Der folgende PHP-Code würde die Serienmail mit der ID 3 nach 14 Tagen versenden:
mailSchedule(value('OI01'), 3, strtotime('+7 days'));
Es können natürlich auch mehrere Serienmails vorbereitet werden:
mailSchedule(value('OI01'), 2, 0);
mailSchedule(value('OI01'), 3, strtotime('+7 days'));
mailSchedule(value('OI01'), 4, strtotime('+14 days'));
Wenn die Möglichkeit besteht, dass der Teilnehmer keine E-Mail-Adresse einträgt, sollte noch ein ''if'' ergänzt werden, um Fehlermeldungen zu vermeiden:
$serial = value('OI01');
if ($serial) {
mailSchedule($serial, 2, 0);
mailSchedule($serial, 3, strtotime('+7 days'));
mailSchedule($serial, 4, strtotime('+14 days'));
}
Beachten Sie, dass die Personenkennung (SERIAL) hier in einer PHP-Variable (''$serial'') zwischengespeichert wird, um sie direkt in den ''mailSchedule()''-Aufrufen zu verwenden. Selbstverständlich könnte hier ebenso ''value('OI01')'' stehen.